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 命令。

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

当你想从命令行运行某个 Package 中的可执行对象时你需要先激活它。该 Package 可以是在 pub.dev 网站、Git 仓库或者你当前设备上。一旦你激活了 Package，就可以参阅 Running a script 运行位于 Package bin 目录下的脚本。

你可以在激活 Package 时指定一个可选的版本限制参数。关于其使用示例请查阅 版本限制参数。

$ dart pub global activate <pub.dev package>

激活 pub.dev 网站上的一个 Package。例如：

$ dart pub global activate markdown

$ 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/

Pub uses the default branch of the Git repository. To specify a different branch or commit, use the --git-ref option:

$ dart pub global activate -sgit https://github.com/dart-lang/http.git --git-ref 36f98e900347335af2338a0e087538009b7de2f9

$ 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 中的脚本。如果你不能直接运行脚本，可以尝试使用 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 <package>:<executable> [args...]

即使某个脚本没有配置成可以从命令行运行，你依然可以使用 pub global run 命令运行它。下述命令传递两个参数从名为 foo 的 Package 运行 bin/bar.dart 脚本。

$ dart pub global run foo:bar arg1 arg2

如果你不是一个 Package 开发者，你可以跳过本节。

Package 可以暴露它的一些脚本以直接从命令行运行。这些脚本必须在 pubspec 文件的 executables 标签下列出。例如，下述名为 helloworld 的 Package 在其 pubspec 文件中将 bin/helloworld.dart 暴露为可以运行：

name: helloworld

executables:
  helloworld:

没有在 executables 标签下列出的脚本可能会降低脚本的易用性：这些脚本虽然可以使用 dart pub global run 命令运行，但是不能直接从命令行运行。

$ dart pub global deactivate <package>

使用 deactivate 命令参数可以将 Package 从全局可用的 Package 列表移除。例如：

$ dart pub global deactivate markdown

此时你不能使用 dart pub global run 命令或从命令行运行该 Package 的脚本。

$ dart pub global list

使用 list 列出当前所有已激活的 Package。

你可以查阅 全局选项 获取 Pub 命令所支持的命令选项。

使用 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

会在全局范围内激活 Package 但不会在 bin 目录下生成任何文件。你必须使用 dart pub global run 来运行任意这些可执行的对象。

将指定的可执行对象添加至你的 PATH 路径中。你可以在一次命令执行中多次使用该选项以添加多个可执行对象到你的 PATH 路径中。

例如，下述命令添加了 foo 中的 bar 和 baz 两个可执行对象（不包括 foo 中定义的其它可执行对象）到你的 PATH 中。

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

默认情况下，如果执行的两个全局 Package 名字冲突了，那么会优先执行最先执行过的那个。但是如果你指定该标识，那么新执行的 Package 则会覆盖之前执行的那些。