进阶 oclif.io 2026-10-18 02:37:03 · 34 阅读
第41章 oclif CLI 发布指南:npm 与独立包策略
# 发布
发布 oclif CLI 主要有两种策略:npm 和独立 tarball。可以只选其一,也可以两者都用。
## npm
和其他 npm 项目一样,直接用 npm publish 即可。发布包里包含一个 run.cmd 脚本,Windows 用户会自动使用它。
$ npm version (major|minor|patch) # 升级版本号、更新 README、添加 git tag
$ npm publish
$ npm install -g mynewcli
$ mynewcli
# 或者
$ npx mynewcli
发布前,你需要在 npm 上注册并验证邮箱地址。 这个流程可以稍作优化:在发布前运行 `npm version major|minor|patch`,它会自动创建 git tag 并提升版本号。 独立 tarball 包 在 CLI 根目录下运行 `oclif pack tarballs` 即可构建独立的 tarball 包。这些包内嵌了 node 二进制文件,因此用户无需预装 node 即可使用 CLI。由于不会将该 node 二进制文件添加到 PATH,它不会与机器上已有的 node 安装产生冲突。 要发布这些包,你可以从 `./dist` 复制文件,或使用 `oclif upload tarballs` 将文件上传到 S3。你需要在 `package.json` 中设置 `oclif.update.s3.bucket` 为有效的 S3 桶,并在环境变量 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 中配置凭证。 将 tarball 包上传到 S3 后,可以使用 `oclif promote` 将其晋升到 S3 中的某个发布渠道。这样能方便地在不同渠道间快速升降特定版本。例如,Salesforce CLI 有独立的 stable 和 stable-rc 渠道,每周更新。 Brew 你的 formula 可以通过 Brew 分发。主要注意事项是:发布时必须设置 `CLIENT_HOME` 变量,否则会破坏更新循环。Heroku CLI 的 formula 中有个例子。通过导出形如 `CLI_NAME_OCLIF_CLIENT_HOME` 的变量(其中 `CLI_NAME` 是你的 CLI 名称),可以强制更新机制查看 brew 的安装位置,而不是默认位置(即 `$XDG_DATA_HOME/.local/share/package_name/client`)。 自动更新器 这些 tarball 包以及下方的安装包都可以通过添加 `@oclif/plugin-update` 插件实现自动更新。只需添加该插件,CLI 就会在后台自动更新,或在运行 `mycli update` 时更新。 如果不想使用 S3,仍可以运行 `oclif pack` 来构建 tarball 包。为了让更新器工作,需将 `package.json` 中的 `oclif.update.s3.host` 设置为托管了 `oclif pack` 在 `./dist` 中生成的文件的主机。该主机不必是 S3 主机。如需自定义 URL 路径,请参见 `@oclif/core` 中的 S3 模板。 自动更新渠道 你可以为发布设置独立的渠道,其运作方式类似于 Google Chrome 渠道(如 beta、dev、canary)。创建渠道时,只需将 `package.json` 中的版本从 `1.0.0` 改为 `1.0.0-beta`("beta" 可以是任意字符串)。随后使用 `oclif pack` 打包时,就会生成 beta 版本的 tarball。用户可以通过 `mycli update beta` 切换到该渠道,并接收该渠道后续的所有发布。 在 Heroku CLI 中,我们在每次提交到 master 分支时自动构建并发布 beta 渠道;而在 CI 中创建 git tag 时,则自动构建并发布 stable 渠道。 Windows 安装包 使用 `oclif pack win` 构建 Windows 安装包,输出到 `./dist/win`。可以通过 `oclif upload win` 上传到 S3,并用 `oclif promote --win` 在 S3 内进行渠道晋升。 `oclif pack win` 依赖 7zip 和 nsis。如果在 mac 或 unix 环境中未安装,可通过 homebrew 安装。 `brew install nsis`
brew install p7zip
对安装程序进行签名 要生成经过签名的安装程序,需设置受限的环境变量_WINDOWS_SIGNING_PASS(例如 MY_CLI_WINDOWS_SIGNING_PASS),并在 package.json 中配置 windows.name 和 windows.keypath:
{
"oclif": {
"windows": {
"name": "My CLI",
"keypath": "path/to/private.key"
}
}
}
请参考 Microsoft 的文档,了解如何为 CLI 获取经过验证的数字签名。 macOS 安装程序 使用 oclif pack macos 构建 macOS .pkg 安装程序。构建产物将输出至 ./dist/macos 目录。你可以使用 oclif upload macos 将其上传至 S3,并通过 oclif promote --macos 在 S3 内部进行晋级处理。需要在 package.json 的 oclif.macos.identifier 中设置 macOS 标识符(我们分别为 Heroku CLI 和 Salesforce CLI 使用 "com.heroku.cli" 和 "com.salesforce.cli" 作为标识符)。 上传至 S3 上传命令默认使用 public-read 访问控制列表(ACL)设置,除非在 package.json 的 oclif.update.s3.acl 中指定了其他策略。但是,创建新的 S3 存储桶时,AWS 的默认配置可能导致在使用 public-read 设置上传时出现访问错误(Code: AccessControlListNotSupported)。 为解决此问题,可以考虑更新 package.json 中 oclif 部分的 ACL 设置。以下示例展示了如何将 acl 设置为 bucket-owner-full-control: {
"oclif": {
"bin": "myOclifApp",
"dirname": "myOclifApp-cli-data",
"update": {
"s3": {
"host": "https://s3.console.aws.amazon.com/",
"bucket": "myOclifApp-cli",
"acl": "bucket-owner-full-control"
}
},
"macos": {
"identifier": "com.myOclifApp.cli"
}
}
}
Amazon 提供了用户指南,协助配置存储桶策略设置。 对安装程序进行签名 要在构建机器上对安装程序进行签名,必须拥有“安装程序签名身份”(有关证书的详细信息,请参见此处的说明)。 请确保在 developer.apple.com 中创建了此类证书,并且该证书已下载并安装在构建机器的钥匙串(KeyChain)中。 证书名称需要在 package.json 的 oclif.macos.sign 中指定。 示例: "macos": {
"identifier": "com.myOclifApp",
"sign": "\"3rd Party Mac Developer Installer: myOclifCompany (R2315646)\""
},
注意转义引号的使用:证书名是作为参数传给 pkgbuild 命令的,没有引号可能会出问题。 对于 Heroku CLI,证书名是 "Developer ID Installer: Heroku INC"。此外还可以通过 OSX_KEYCHAIN 指定 keychain。 构建机器上已安装的证书可以在 Keychain Access 应用中查看。 Ubuntu/Debian 软件包 使用 oclif pack deb 构建 deb 包。把 MYCLI_DEB_KEY 设置为 gpg key id 即可生成 gpg 文件。这样 ./dist/deb 目录下会包含 apt 仓库所需的全部文件。可以用 oclif upload deb 上传到 S3,再用 oclif promote --deb 在 S3 内进行 promote 操作。 发布到 S3 后,用户可以通过以下命令安装: $ wget -qO- https://mys3bucket.s3.amazonaws.com/apt/release.key | apt-key add - # you will need to upload this file manually
$ sudo echo "deb https://mys3bucket.s3.amazonaws.com/apt ./" > /etc/apt/sources.list.d/mycli.list
$ sudo apt update
$ sudo apt install -y mycli
也可以把上面的命令放进一个脚本,让用户通过 curl https://pathto/myscript | sh 来安装。 这类包不会自动更新,因为 Ubuntu 本身已经为用户提供了可靠的包更新机制。 Snapcraft Snap 是分发 Linux CLI 的好方式,且 Ubuntu 16+ 已内置支持。只需简单修改 Heroku CLI 的 snapcraft.yml 文件,就能用于任何 oclif CLI。
$ npm publish
$ npm install -g mynewcli
$ mynewcli
# 或者
$ npx mynewcli
发布前,你需要在 npm 上注册并验证邮箱地址。 这个流程可以稍作优化:在发布前运行 `npm version major|minor|patch`,它会自动创建 git tag 并提升版本号。 独立 tarball 包 在 CLI 根目录下运行 `oclif pack tarballs` 即可构建独立的 tarball 包。这些包内嵌了 node 二进制文件,因此用户无需预装 node 即可使用 CLI。由于不会将该 node 二进制文件添加到 PATH,它不会与机器上已有的 node 安装产生冲突。 要发布这些包,你可以从 `./dist` 复制文件,或使用 `oclif upload tarballs` 将文件上传到 S3。你需要在 `package.json` 中设置 `oclif.update.s3.bucket` 为有效的 S3 桶,并在环境变量 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 中配置凭证。 将 tarball 包上传到 S3 后,可以使用 `oclif promote` 将其晋升到 S3 中的某个发布渠道。这样能方便地在不同渠道间快速升降特定版本。例如,Salesforce CLI 有独立的 stable 和 stable-rc 渠道,每周更新。 Brew 你的 formula 可以通过 Brew 分发。主要注意事项是:发布时必须设置 `CLIENT_HOME` 变量,否则会破坏更新循环。Heroku CLI 的 formula 中有个例子。通过导出形如 `CLI_NAME_OCLIF_CLIENT_HOME` 的变量(其中 `CLI_NAME` 是你的 CLI 名称),可以强制更新机制查看 brew 的安装位置,而不是默认位置(即 `$XDG_DATA_HOME/.local/share/package_name/client`)。 自动更新器 这些 tarball 包以及下方的安装包都可以通过添加 `@oclif/plugin-update` 插件实现自动更新。只需添加该插件,CLI 就会在后台自动更新,或在运行 `mycli update` 时更新。 如果不想使用 S3,仍可以运行 `oclif pack` 来构建 tarball 包。为了让更新器工作,需将 `package.json` 中的 `oclif.update.s3.host` 设置为托管了 `oclif pack` 在 `./dist` 中生成的文件的主机。该主机不必是 S3 主机。如需自定义 URL 路径,请参见 `@oclif/core` 中的 S3 模板。 自动更新渠道 你可以为发布设置独立的渠道,其运作方式类似于 Google Chrome 渠道(如 beta、dev、canary)。创建渠道时,只需将 `package.json` 中的版本从 `1.0.0` 改为 `1.0.0-beta`("beta" 可以是任意字符串)。随后使用 `oclif pack` 打包时,就会生成 beta 版本的 tarball。用户可以通过 `mycli update beta` 切换到该渠道,并接收该渠道后续的所有发布。 在 Heroku CLI 中,我们在每次提交到 master 分支时自动构建并发布 beta 渠道;而在 CI 中创建 git tag 时,则自动构建并发布 stable 渠道。 Windows 安装包 使用 `oclif pack win` 构建 Windows 安装包,输出到 `./dist/win`。可以通过 `oclif upload win` 上传到 S3,并用 `oclif promote --win` 在 S3 内进行渠道晋升。 `oclif pack win` 依赖 7zip 和 nsis。如果在 mac 或 unix 环境中未安装,可通过 homebrew 安装。 `brew install nsis`
brew install p7zip
对安装程序进行签名 要生成经过签名的安装程序,需设置受限的环境变量
"oclif": {
"windows": {
"name": "My CLI",
"keypath": "path/to/private.key"
}
}
}
请参考 Microsoft 的文档,了解如何为 CLI 获取经过验证的数字签名。 macOS 安装程序 使用 oclif pack macos 构建 macOS .pkg 安装程序。构建产物将输出至 ./dist/macos 目录。你可以使用 oclif upload macos 将其上传至 S3,并通过 oclif promote --macos 在 S3 内部进行晋级处理。需要在 package.json 的 oclif.macos.identifier 中设置 macOS 标识符(我们分别为 Heroku CLI 和 Salesforce CLI 使用 "com.heroku.cli" 和 "com.salesforce.cli" 作为标识符)。 上传至 S3 上传命令默认使用 public-read 访问控制列表(ACL)设置,除非在 package.json 的 oclif.update.s3.acl 中指定了其他策略。但是,创建新的 S3 存储桶时,AWS 的默认配置可能导致在使用 public-read 设置上传时出现访问错误(Code: AccessControlListNotSupported)。 为解决此问题,可以考虑更新 package.json 中 oclif 部分的 ACL 设置。以下示例展示了如何将 acl 设置为 bucket-owner-full-control: {
"oclif": {
"bin": "myOclifApp",
"dirname": "myOclifApp-cli-data",
"update": {
"s3": {
"host": "https://s3.console.aws.amazon.com/",
"bucket": "myOclifApp-cli",
"acl": "bucket-owner-full-control"
}
},
"macos": {
"identifier": "com.myOclifApp.cli"
}
}
}
Amazon 提供了用户指南,协助配置存储桶策略设置。 对安装程序进行签名 要在构建机器上对安装程序进行签名,必须拥有“安装程序签名身份”(有关证书的详细信息,请参见此处的说明)。 请确保在 developer.apple.com 中创建了此类证书,并且该证书已下载并安装在构建机器的钥匙串(KeyChain)中。 证书名称需要在 package.json 的 oclif.macos.sign 中指定。 示例: "macos": {
"identifier": "com.myOclifApp",
"sign": "\"3rd Party Mac Developer Installer: myOclifCompany (R2315646)\""
},
注意转义引号的使用:证书名是作为参数传给 pkgbuild 命令的,没有引号可能会出问题。 对于 Heroku CLI,证书名是 "Developer ID Installer: Heroku INC"。此外还可以通过 OSX_KEYCHAIN 指定 keychain。 构建机器上已安装的证书可以在 Keychain Access 应用中查看。 Ubuntu/Debian 软件包 使用 oclif pack deb 构建 deb 包。把 MYCLI_DEB_KEY 设置为 gpg key id 即可生成 gpg 文件。这样 ./dist/deb 目录下会包含 apt 仓库所需的全部文件。可以用 oclif upload deb 上传到 S3,再用 oclif promote --deb 在 S3 内进行 promote 操作。 发布到 S3 后,用户可以通过以下命令安装: $ wget -qO- https://mys3bucket.s3.amazonaws.com/apt/release.key | apt-key add - # you will need to upload this file manually
$ sudo echo "deb https://mys3bucket.s3.amazonaws.com/apt ./" > /etc/apt/sources.list.d/mycli.list
$ sudo apt update
$ sudo apt install -y mycli
也可以把上面的命令放进一个脚本,让用户通过 curl https://pathto/myscript | sh 来安装。 这类包不会自动更新,因为 Ubuntu 本身已经为用户提供了可靠的包更新机制。 Snapcraft Snap 是分发 Linux CLI 的好方式,且 Ubuntu 16+ 已内置支持。只需简单修改 Heroku CLI 的 snapcraft.yml 文件,就能用于任何 oclif CLI。