tars-deploy

tars-deploy 是一个用于为 TARS 框架打包 Node.js 服务的命令行工具。它会把服务目录按 TARS 要求组织成一个带有 tars_nodejs 运行时目录的可部署压缩包（.tgz）。

仓库路径: tars-deploy

安装

推荐全局安装以在任意服务目录中使用：

npm install -g @cicctencent/tars-deploy

或者使用 pnpm / cnpm 安装：

pnpm add -g @cicctencent/tars-deploy

快速示例

在你的服务根目录（包含 package.json）执行：

tars-deploy MyService

执行成功后会在当前目录生成 MyService.tgz 文件，里面包含按 TARS 格式组织的目录结构。

使用说明

基本调用格式：

tars-deploy <packname> [options]

• <packname>: 必填，打包后生成的服务名（只允许字母和数字，正则为 /^[0-9a-z]+$/i）。
• 请在服务工程的根目录运行（即包含服务 package.json 的目录）。

生成过程会创建一个临时目录 _ <name>_<timestamp>，在其中组装目录结构，最后打包为 <name>.tgz，并在完成后清理临时目录。

可用选项

• -p, --platform <platform>: 指定目标平台，支持 linux 或 darwin（默认 linux）。
• -c, --copy: 启用 node_modules 复制模式，打包时不再通过网络在 src 下执行 npm install，而是直接复制上层目录的 node_modules 到 src/node_modules（当上层存在 node_modules 时）。
• --pnpm: 使用 pnpm 执行安装命令（exec 时选择 pnpm）。
• --cnpm: 使用 cnpm 执行安装命令（exec 时选择 cnpm）。
• --delbin: 在打包前删除 src/node_modules/.bin 文件夹（用于移除软链接等可能导致问题的内容）。
• --legacy-peer-deps: 安装依赖时传递 --legacy-peer-deps，用于跳过 peerDependencies 冲突。
• -V, --version: 输出工具版本。
• -h, --help: 输出帮助信息。

示例：

tars-deploy MyService --pnpm --delbin
tars-deploy MyService -p darwin
tars-deploy MyService --copy

注意：CLI 会在启动时输出当前 Node 版本、Node 可执行路径、系统平台与架构等信息。如果当前系统不是 linux，会有警告提示建议在 Linux 下打包。

打包流程（概要）

主要步骤如下：

1. 创建临时目录结构：_<name>_<timestamp>/<name>/<name>/src 等。
2. 根据 tars.json 的 includes 或当前目录内容把指定文件/目录复制到临时 src 中。
3. 拷贝 Node 可执行文件到 tars_nodejs/node（来源顺序：环境变量 NODE_EXEC_PATH -> tars.json 的 nodeExecPath -> 当前 process.execPath）。
4. 安装或拷贝 @tars/node-agent 到 tars_nodejs/node-agent（支持通过 pnpm/cnpm 安装）。
5. 在 src 中安装生产依赖（或复制上层 node_modules，取决于 --copy）。可以通过 --legacy-peer-deps 跳过 peer 依赖冲突。
6. 可选择性地对 C/C++ 模块执行 rebuild（仅在 Linux 下支持编译本机模块）。
7. 执行打包前钩子（prePack），例如删除 .bin。
8. 使用 tar 将临时目录打包为 <name>.tgz。
9. 清理临时目录。

tars.json 配置说明

tars-deploy 在当前服务目录查找 tars.json（若存在会读取并应用配置）。默认示例：

{
	"includes": ["dist", "view", "package.json", "bootstrap.js", "server.js"],
	"nodeExecPath": ""
}

配置字段说明：

• includes（数组， 可选）: 指定需要从服务根目录拷贝到打包 src 中的文件或文件夹名称列表（按顺序）。如果未配置 includes，打包脚本会默认复制除了临时目录之外的所有顶层文件/目录。

  • 举例：["dist","view","package.json","server.js"] 会只把这些项复制进最终包的 src。
  • 注意：这里的条目是相对于服务根目录的路径或文件名。

• nodeExecPath（字符串， 可选）: 指定用于打包时拷贝到 tars_nodejs/node 的 node 可执行文件路径，优先级低于环境变量 NODE_EXEC_PATH，高于默认 process.execPath。

  • 举例："/usr/local/node/bin/node"。
  • 如果为空或未设置，将使用运行 tars-deploy 的 Node 可执行文件（process.execPath），或使用环境变量 NODE_EXEC_PATH 以覆盖。

使用建议：

• 在跨平台打包（例如在 macOS 上打包 Linux 可执行文件）时，请在 tars.json 指定合适的 nodeExecPath，或在打包环境中把 NODE_EXEC_PATH 设置为目标平台的 node 二进制路径。

关于本地依赖、复制与构建

• --copy：当上层目录存在 node_modules 时，启用此选项会将其复制到临时 src/node_modules，避免在封包过程中联网拉取依赖，适用于内网或离线打包场景。
• 如果 src 目录中有 binding.gyp 或本地 C/C++ 扩展，需要在 Linux 下执行 rebuild（脚本会在 Linux 下调用 node-gyp rebuild），否则该步骤会跳过。

常见问题 & 注意事项

• 包名限制：只允许字母和数字，建议首字母大写（非必须）。
• 若你的服务需要特定 Node 版本，请确保打包时拷贝的 node 可执行文件与目标运行环境一致（通过 tars.json.nodeExecPath 或 NODE_EXEC_PATH 指定）。
• 如果你在非 Linux 系统上打包并且包含本机模块（native addons），请在 Linux 机上重新打包或交叉编译对应的二进制。

作者与许可

本工具基于 TARS 开源工具链，详细实现见仓库代码。