目錄

套件版面配置慣例

目錄 keyboard_arrow_down keyboard_arrow_up
more_horiz

當您建立 pub 套件時，我們鼓勵您遵循本頁所描述的慣例。它們描述您如何在套件中組織檔案和目錄，以及如何命名事物。

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

enchilada/
  .dart_tool/ *
  pubspec.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.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 內的程式庫是公開可見的：其他套件可以自由匯入它們。但是套件的大部分程式碼是內部實作程式庫，應該只由套件本身匯入和使用。這些程式庫會放在名為 src 的 lib 子目錄中。您可以在其中建立子目錄，如果它有助於您組織事物。

您可以自由地從相同套件中的其他 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

對於網頁套件，請將進入點程式碼（包含 main() 的 Dart 腳本以及支援檔案，例如 CSS 或 HTML）放置於 web 目錄下。您可以將 web 目錄組織成子目錄。

將函式庫程式碼置於 lib 下。如果該函式庫並非由 web 下的程式碼或其他套件直接匯入，請將其置於 lib/src 下。將基於網頁的範例置於 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]/套件名稱.dart
  • example[/lib]/套件名稱_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 的目錄中。

Hook

#
enchilada/
  hook/
    build.dart

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

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

工具的專案特定快取

#

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

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

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

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

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

除非另有說明，否則本網站上的文件反映的是 Dart 3.6.0。頁面最後更新時間：2024-12-10。 檢視來源 或 回報問題。