dart pub global 命令

Global 命令是 Pub 工具 中的一個命令。

Pub 的 global 選項允許你在任意位置下從命令列執行 Dart 指令碼。在 啟用 Package 後，你可以 執行 該 Package bin 目錄下的指令碼。 停用 Package 後你可以從全域可用的 Package 列表中將其移除。

例如，假設你想要透過命令使用 webdev 來部署您的 Dart Web 應用。

$ dart pub global activate webdev
$ webdev serve

如果該操作無效，你可能需要 設定你的路徑。

如果想要從 Package 中執行 Dart 指令碼，或者從 Package 所依賴的其它 Package 中執行指令碼，請查閱 dart run 命令。

Package 啟用

dart pub global activate [--noexecutables] [--executable=<name>] [--overwrite] <package> [version-constraint]

當你想從命令列執行某個 Package 中的可執行物件時你需要先啟用它。該 Package 可以是在 pub.dev 網站、Git 儲存庫或者你當前裝置上。一旦你激活了 Package，就可以參閱 Running a script 執行位於 Package bin 目錄下的指令碼。

你可以在啟用 Package 時指定一個可選的版本限制引數。關於其使用範例請查閱 版本限制引數。

啟用 pub.dev 網站上的 Package

$ dart pub global activate <pub.dev package>

啟用 pub.dev 網站上的一個 Package。例如：

$ dart pub global activate markdown

啟用 Git 儲存庫中的 Package

$ dart pub global activate --source git <Git URL>
$ dart pub global activate -sgit <Git URL>

使用 --source git（或 -sgit 簡寫）命令引數可以啟用位於 Git 儲存庫中的 Package。下面的兩個範例都可以用於啟用位於 GitHub 網站上名為 async_await 的 Package。

$ dart pub global activate --source git https://github.com/dart-lang/async_await.git
$ dart pub global activate -sgit https://github.com/dart-lang/async_await.git

Pub 會嘗試在 Git 儲存庫的根目錄尋找 package。你可以使用 --git-path 選項為 Pub 指定用於查詢的相對於儲存庫的路徑：

$ dart pub global activate -sgit https://github.com/dart-lang/http.git --git-path pkgs/http/

啟用當前裝置上的 Package

$ dart pub global activate --source path <path>

使用 activate --source path <path> 命令引數啟用當前裝置上的 Package。下面的範例激活了位於 ~/dart 目錄下名為 stopwatch 的 Package。

$ dart pub global activate --source path ~/dart/stopwatch

更新已經啟用的 Package

你可以再次啟用一個已經啟用的 Package 以更新它。

執行指令碼

你可以從命令列直接執行已啟用 Package 中的指令碼。如果你不能直接執行指令碼，可以嘗試使用 dart pub global run 命令。

執行指定路徑中的指令碼

在從命令列直接執行指令碼前，你還需要將 系統快取 的 bin 檔案目錄新增至 PATH 路徑中。 For example, say you’ve activated the webdev package, but you still can’t run the command:

例如，假設你已經激活了名為 webdev 的套件，但是你依然不能執行它：

$ dart pub global activate webdev
$ webdev serve
-bash: webdev: command not found

此時你需要確認 Pub 系統快取的 bin 目錄是否已經新增至 PATH 路徑中。例如在 macOS 上，使用下述命令可以檢視你的 PATH 路徑是否已經包含了 Pub 系統快取的 bin 目錄：

$ echo $PATH
/Users/<user>/homebrew/bin:/usr/local/bin:/usr/bin:/bin:[!/Users/<user>/.pub-cache/bin!]

如果 PATH 路徑中沒有新增 Pub 快取目錄，你需要根據你當前裝置的系統平台找到對應的 Pub 快取目錄並將之新增。

^* 對於不同版本的 Windows 系統，Pub 系統快取的確切位置可能有所不同。

現在你可以直接呼叫命令了：

$ cd web_project
$ webdev serve

如果此時從命令列執行指令碼依然失敗，則 Package 可能沒有針對此功能進行 配置。但你仍然可以使用 dart pub global run 命令執行它。

使用 dart pub global run 命令執行指令碼

$ dart pub global run <package>:<executable> [args...]

即使某個指令碼沒有配置成可以從命令列執行，你依然可以使用 pub global run 命令執行它。下述命令傳遞兩個引數從名為 foo 的 Package 執行 bin/bar.dart 指令碼。

$ dart pub global run foo:bar arg1 arg2

配置 Package 為可執行的

如果你不是一個 Package 開發者，你可以跳過本節。

Package 可以暴露它的一些指令碼以直接從命令列執行。這些指令碼必須在 pubspec 檔案的 executables 標籤下列出。例如，下述名為 helloworld 的 Package 在其 pubspec 檔案中將 bin/helloworld.dart 暴露為可以執行：

name: helloworld

executables:
  helloworld:

沒有在 executables 標籤下列出的指令碼可能會降低指令碼的易用性：這些指令碼雖然可以使用 dart pub global run 命令執行，但是不能直接從命令列執行。

停用 Package

$ dart pub global deactivate <package>

使用 deactivate 命令引數可以將 Package 從全域可用的 Package 列表移除。例如：

$ dart pub global deactivate markdown

此時你不能使用 dart pub global run 命令或從命令列執行該 Package 的指令碼。

列出啟用的 Package

$ dart pub global list

使用 list 列出當前所有已啟用的 Package。

選項

你可以查閱 全域選項 獲取 Pub 命令所支援的命令選項。

[version-constraint]

使用 dart pub global activate 拉取 Package 的指定版本。例如，下述命令會拉取 markdown 這個 Package 的 0.6.0 版本：

$ dart pub global activate markdown 0.6.0

如果你指定的是一個範圍，Pub 則會在這個範圍內選取一個最適合的版本。例如：

$ dart pub global activate foo <3.0.0

--no-executables

會在全域範圍內啟用 Package 但不會在 bin 目錄下產生任何檔案。你必須使用 dart pub global run 來執行任意這些可執行的物件。

--executable=<name> 或 -x <name>

將指定的可執行物件新增至你的 PATH 路徑中。你可以在一次命令執行中多次使用該選項以新增多個可執行物件到你的 PATH 路徑中。

例如，下述命令添加了 foo 中的 bar 和 baz 兩個可執行物件（不包括 foo 中定義的其它可執行物件）到你的 PATH 中。

$ dart pub global activate foo -x bar -x baz

--overwrite

預設情況下，如果執行的兩個全域 Package 名字衝突了，那麼會優先執行最先執行過的那個。但是如果你指定該標識，那麼新執行的 Package 則會覆蓋之前執行的那些。