跳至主要內容
目錄

套件版面配置慣例

目錄 keyboard_arrow_down keyboard_arrow_up
more_horiz

當您建置pub 套件時，我們鼓勵您遵循本頁面描述的慣例。這些慣例描述如何組織套件內部的檔案和目錄，以及如何命名事物。

以下是一個完整套件 (名為 enchilada) 的範例，它使用了這些指南的每個角落

enchilada/
  .dart_tool/ *
  pubspec.yaml
  pubspec_overrides.yaml **
  pubspec.lock ***
  LICENSE
  README.md
  CHANGELOG.md
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ****
    getting_started.md
  example/
    main.dart
  hook/
    build.dart
  integration_test/
    app_test.dart
  lib/
    enchilada.dart
    tortilla.dart
    guacamole.css
    src/
      beans.dart
      queso.dart
  test/
    enchilada_test.dart
    tortilla_test.dart
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

* .dart_tool/ 目錄在您執行 dart pub get 後存在。請勿將其簽入原始碼控制。若要瞭解更多資訊，請參閱工具的專案特定快取。

** pubspec_overrides.yaml 檔案 (如果存在) 會覆寫 pubspec.yaml 的某些方面。通常您不希望將其簽入原始碼控制。

*** pubspec.lock 檔案在您執行 dart pub get 後存在。除非您的套件是應用程式套件，否則請將其從原始碼控制中排除。

**** doc/api 目錄在您執行 dart doc 後在本機存在。請勿將 api 目錄簽入原始碼控制。

pubspec

#
enchilada/
  pubspec.yaml
  pubspec.lock

每個套件都有一個 pubspec，一個名為 pubspec.yaml 的檔案，位於套件的根目錄中。這就是使其成為套件的原因。

在套件上執行 dart pub get、dart pub upgrade 或 dart pub downgrade 會建立一個鎖定檔，名為 pubspec.lock。如果您的套件是應用程式套件，請將鎖定檔簽入原始碼控制。否則，請勿這樣做。

如需更多資訊，請參閱 pubspec 頁面。

LICENSE

#
enchilada/
  LICENSE

如果您要發佈套件，請包含一個名為 LICENSE 的授權檔案。我們建議使用OSI 核准的授權，例如 BSD-3-Clause，以便其他人可以重複使用您的作品。

README.md

#
enchilada/
  README.md

在開放原始碼中非常常見的一個檔案是 README 檔案，它描述了專案。這在 pub 中尤其重要。當您上傳到 pub.dev 網站時，您的 README.md 檔案會顯示在您的套件頁面上，並以 Markdown 格式呈現。這是向人們介紹您的程式碼的絕佳位置。

如需關於如何撰寫出色的 README 的指南，請參閱撰寫套件頁面。

CHANGELOG.md

#
enchilada/
  CHANGELOG.md

包含一個 CHANGELOG.md 檔案，其中包含套件每個版本的章節，並附帶說明，以協助您的套件使用者升級。您的套件使用者通常會檢閱變更日誌，以發現錯誤修正和新功能，或確定升級到最新版本的套件需要多少努力。

為了支援剖析 CHANGELOG.md 的工具，請使用以下格式

  • 每個版本都有自己的章節，帶有標題。
  • 版本標題可以是全部為層級 1 或全部為層級 2。
  • 版本標題文字包含套件版本號碼，可選擇性地加上 "v" 前綴。

當您將套件上傳到 pub.dev 網站時，您的套件的 CHANGELOG.md 檔案 (如果有的話) 會顯示在變更日誌標籤中，並以 Markdown 格式呈現。

以下是一個 CHANGELOG.md 檔案的範例。如範例所示，您可以新增子章節。

markdown
# 1.0.1

* Fixed missing exclamation mark in `sayHi()` method.

# 1.0.0

* **Breaking change:** Removed deprecated `sayHello()` method.
* Initial stable release.

## Upgrading from 0.1.x

Change all calls to `sayHello()` to instead be to `sayHi()`.

# 0.1.1

* Deprecated the `sayHello()` method; use `sayHi()` instead.

# 0.1.0

* Initial development release.

公開目錄

#

您的套件中有兩個目錄對其他套件公開：lib 和 bin。您將公開程式庫放在 lib 中，將公開工具放在 bin 中。

公開程式庫

#

以下目錄結構顯示了 enchilada 的 lib 部分

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

許多套件定義了其他套件可以匯入和使用的 Dart 程式庫。這些公開的 Dart 程式庫檔案放在名為 lib 的目錄中。

大多數套件定義了單個程式庫，使用者可以匯入。在這種情況下，其名稱通常應與套件的名稱相同，例如此處範例中的 enchilada.dart。但是您也可以定義其他程式庫，並使用對您的套件有意義的任何名稱。

當您這樣做時，使用者可以使用套件的名稱和程式庫檔案來匯入這些程式庫，如下所示

dart
import 'package:enchilada/enchilada.dart';
import 'package:enchilada/tortilla.dart';

如果您想組織您的公開程式庫，您也可以在 lib 內部建立子目錄。如果您這樣做，使用者將在匯入時指定該路徑。假設您有以下檔案階層

enchilada/
  lib/
    some/
      path/
        olives.dart

使用者匯入 olives.dart，如下所示

dart
import 'package:enchilada/some/path/olives.dart';

請注意，只有程式庫應該放在 lib 中。進入點—帶有 main() 函式的 Dart 腳本—不能放在 lib 中。如果您將 Dart 腳本放在 lib 內部，您會發現它包含的任何 package: 匯入都無法解析。相反地，您的進入點應放在適當的進入點目錄中。

如需有關套件的更多資訊，請參閱建立套件。

公開工具

#

放置在 bin 目錄內部的 Dart 腳本是公開的。如果您在套件的目錄內，您可以使用 dart run 從套件所依賴的任何其他套件的 bin 目錄執行腳本。從任何目錄，您可以執行腳本，從您已使用 dart pub global activate 啟動的套件執行腳本。

如果您打算讓您的套件被依賴，並且您希望您的腳本對您的套件是私有的，請將它們放在頂層 tool 目錄中。如果您不打算讓您的套件被依賴，您可以將您的腳本留在 bin 中。

公開資源

#
enchilada/
  lib/
    guacamole.css

雖然大多數套件的存在是為了讓您重複使用 Dart 程式碼，但您也可以重複使用其他種類的內容。例如，Bootstrap 的套件可能包含許多 CSS 檔案，供套件的使用者使用。

這些檔案放在頂層 lib 目錄中。您可以將任何種類的檔案放在那裡，並使用子目錄以您喜歡的任何方式組織它。

實作檔案

#
enchilada/
  lib/
    src/
      beans.dart
      queso.dart

lib 內部的程式庫是公開可見的：其他套件可以自由匯入它們。但是，套件的大部分程式碼是內部實作程式庫，這些程式庫應該僅由套件本身匯入和使用。這些程式庫放在 lib 的一個名為 src 的子目錄內。如果子目錄有助於您組織事物，您可以在其中建立子目錄。

您可以自由地從同一個套件中的其他 Dart 程式碼 (例如 lib 中的其他程式庫、bin 中的腳本和測試) 匯入位於 lib/src 中的程式庫，但您永遠不應從另一個套件的 lib/src 目錄匯入。這些檔案不是套件公開 API 的一部分，它們可能會以可能破壞您的程式碼的方式變更。

從您自己的套件內部匯入程式庫的方式取決於程式庫的位置

例如

lib/beans.dart
dart
// When importing from within lib:
import 'src/beans.dart';
test/beans_test.dart
dart
// When importing from outside lib:
import 'package:enchilada/src/beans.dart';

您在此處使用的名稱 (在本例中為 enchilada) 是您在套件的 pubspec 中為套件指定的名稱。

Web 檔案

#
enchilada/
  web/
    index.html
    main.dart
    style.css

對於 Web 套件，請將進入點程式碼—包含 main() 和支援檔案 (例如 CSS 或 HTML) 的 Dart 腳本—放在 web 下。您可以將 web 目錄組織成子目錄 (如果您願意)。

將程式庫程式碼放在 lib 下。如果程式庫不是由 web 下的程式碼或另一個套件直接匯入，請將其放在 lib/src 下。將基於 Web 的範例放在 example 下。請參閱公開資源，以取得關於將資源 (例如圖片) 放在哪裡的提示。

命令列應用程式

#
enchilada/
  bin/
    enchilada

有些套件定義了可以直接從命令列執行的程式。這些程式可以是 Shell 腳本或任何其他腳本語言，包括 Dart。

如果您的套件定義了像這樣的程式碼，請將其放在名為 bin 的目錄中。如果您使用 dart pub global 進行設定，您可以從命令列上的任何位置執行該腳本。

測試和基準測試

#
enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

每個套件都應該有測試。使用 pub，慣例是大多數測試都放在 test 目錄 (或其中的某個目錄，如果您願意) 中，並且檔案名稱的結尾帶有 _test。

通常，這些測試會使用 test 套件。

enchilada/
  integration_test/
    app_test.dart

Flutter 應用程式套件也可能具有特殊的整合測試，這些測試使用 integration_test 套件。這些測試位於它們自己的 integration_test 目錄中。

其他套件可能會選擇遵循類似的模式，將較慢的整合測試與單元測試分開，但請注意，預設情況下 dart test 不會執行這些測試。您必須使用 dart test integration_test 明確地執行它們。

enchilada/
  benchmark/
    make_lunch.dart

具有效能關鍵程式碼的套件也可能包含基準測試。這些測試 API 不是為了正確性，而是為了速度 (或記憶體使用量，或可能其他經驗指標)。

文件

#
enchilada/
  doc/
    api/
    getting_started.md

如果您有程式碼和測試，您可能需要的下一個部分是良好的文件。這些文件放在名為 doc 的目錄中。

當您執行 dart doc 工具時，預設情況下，它會將 API 文件放在 doc/api 下。由於 API 文件是從原始碼產生的，因此您不應將其放在原始碼控制之下。

除了產生的 api 之外，我們對於您撰寫的文件格式或組織沒有任何指南。請使用您偏好的任何標記格式。

範例

#
enchilada/
  example/
    main.dart

程式碼、測試、文件，您的使用者還想要什麼？當然是使用您的套件的獨立範例程式！這些範例程式放在 example 目錄中。如果範例很複雜且使用多個檔案，請考慮為每個範例建立一個目錄。否則，您可以將每個範例直接放在 example 中。

在您的範例中，使用 package: 從您自己的套件匯入檔案。這可確保您套件中的範例程式碼看起來與您套件外部的程式碼完全相同。

如果您可能會發佈您的套件，請考慮建立一個具有以下名稱之一的範例檔案

  • example/example[.md]
  • example[/lib]/main.dart
  • example[/lib]/package_name.dart
  • example[/lib]/package_name_example.dart
  • example[/lib]/example.dart
  • example/README[.md]

當您發佈包含上述一個或多個檔案的套件時，pub.dev 網站會建立一個範例標籤，以顯示它找到的第一個檔案 (依上述清單中顯示的順序搜尋)。例如，如果您的套件在其 example 目錄下有許多檔案，包括一個名為 README.md 的檔案，那麼您套件的「範例」標籤將顯示 example/README.md 的內容 (以 Markdown 格式剖析)。

內部工具和腳本

#
enchilada/
  tool/
    generate_docs.dart

成熟的套件通常有小型輔助腳本和程式，人們在開發套件本身時執行這些腳本和程式。想想看，像是測試執行器、文件產生器或其他自動化程式碼片段。

與 bin 中的腳本不同，這些腳本不是給套件的外部使用者使用的。如果您有任何這些腳本，請將它們放在名為 tool 的目錄中。

Hooks

#
enchilada/
  hook/
    build.dart

套件可以定義由 Dart 和 Flutter SDK 呼叫的 Hooks。這些 Hooks 具有預定義的 CLI，如果存在，將由 SDK 工具呼叫。

由於這些 Hooks 是由 dart 和 flutter 工具在執行和建置時呼叫的，因此這些 Hooks 的相依性必須是正常的相依性，而不是 dev_dependencies。

工具的專案特定快取

#

.dart_tool/ 目錄在您執行 dart pub get 時建立，並且可能隨時刪除。各種工具使用此目錄來快取特定於您的專案和/或本機機器的檔案。.dart_tool/ 目錄永遠不應簽入原始碼控制，或在機器之間複製。

刪除 .dart_tool/ 目錄通常也是安全的，儘管某些工具可能需要重新計算快取資訊。

範例： dart pub get 工具將下載相依性並將其解壓縮到全域 $PUB_CACHE 目錄，然後寫入 .dart_tool/package_config.json 檔案，將套件名稱對應到全域 $PUB_CACHE 目錄中的目錄。.dart_tool/package_config.json 檔案供其他工具使用，例如分析器和編譯器，當它們需要解析諸如 import 'package:foo/foo.dart' 之類的語句時。

當開發需要專案特定快取的工具時，您可以考慮使用 .dart_tool/ 目錄，因為大多數使用者已經使用 .gitignore 忽略了它。當在使用者的 .dart_tool/ 目錄中快取工具的檔案時，您應該使用唯一的子目錄。為了避免衝突，.dart_tool/<tool_package_name>/ 形式的子目錄保留給名為 <tool_package_name> 的套件使用。如果您的工具不是透過 pub.dev 網站發佈的，您可以考慮發佈一個佔位符套件，以便保留唯一的名稱。

範例： package:build 提供了一個用於撰寫程式碼產生步驟的框架。當執行這些建置步驟時，檔案會快取在 .dart_tool/build/ 中。這有助於加速未來重新執行建置步驟的速度。

除非另有說明，否則本網站上的文件反映的是 Dart 3.7.1。頁面上次更新於 2025-02-28。 檢視原始碼 或 回報問題。