pnpm zip命令详解

pnpm zip 是 pnpm 自 v7.0.0 起引入的实验性命令，用于将项目打包成一个 ZIP 格式 的归档文件。它通常用于快速发布、无网络环境部署或分发整个项目（包括其依赖）。

基本用法

pnpm zip [options] [package-name]

• 如果不指定 package-name，默认打包当前工作目录下的项目。
• 在 monorepo 中，可以使用 --filter 指定子项目。

常用选项

选项	类型	说明
--standalone	布尔	将项目及其所有依赖打包进 ZIP （包括 node_modules）
--output <path>	字符串	指定 ZIP 文件的输出路径和文件名（默认 ./<pkg-name>-<version>.zip）
--filter <pattern>	字符串	在 monorepo 中过滤要打包的子项目（例如 --filter @my-scope/foo）
--no-optional	布尔	打包时不包含可选依赖
--force	布尔	如果输出文件已存在，强制覆盖
--config <key=value>	键值对	临时覆盖 pnpm 配置（如 --config.use-node-version=18）

注意 ：--standalone 是核心选项。不添加此选项时，ZIP 仅包含项目源文件（类似 pnpm pack 但输出格式为 ZIP）；添加后，会把所有 resolved 的依赖（包括 transitive dependencies）也放入 ZIP，形成一个自包含的部署包。

与 pnpm pack 的区别

特性	pnpm pack	pnpm zip
输出格式	.tgz (tarball)	.zip (ZIP)
默认内容	仅项目源文件 + package.json	仅项目源文件（不含依赖）
--standalone 行为	无	打包所有依赖（模拟扁平化的 node_modules）
主要用途	发布到 npm registry	快速部署、离线分发、CI/CD 归档

典型使用场景

1. 打包单项目（包含依赖）为自部署 ZIP

cd my-app
pnpm zip --standalone --output ./deploy.zip

生成一个包含 node_modules 的 ZIP，解压后可直接运行（确保目标环境 Node.js 版本一致）。

2. 在 monorepo 中打包特定子项目

# 打包 packages/backend 项目（含依赖）
pnpm zip --filter @my-project/backend --standalone

生成的 ZIP 文件名为 backend-1.0.0.zip（版本号取自 package.json）。

3. 仅打包源码（不包含依赖）

pnpm zip --output ./source-code.zip

得到只包含项目文件（src/, package.json, README.md 等）的 ZIP。

4. 排除可选依赖以减小体积

pnpm zip --standalone --no-optional

注意事项

1. 实验性特性 ：pnpm zip 的功能和选项可能在后续版本中变化。执行前建议查看 pnpm --help 确认当前版本支持。
2. 性能 ：大型项目使用 --standalone 时，打包时间可能较长（需要解析和复制所有依赖）。
3. 兼容性 ：生成的 ZIP 文件中的 node_modules 结构是扁平化的（类似 npm/yarn 的扁平布局），而不是 pnpm 原本的符号链接结构。这确保了在其他环境中可以正常使用，但可能不完全等同于 pnpm 原生的依赖解析。
4. 配置影响 ：pnpm zip 会遵循 package.json 中的 files 字段、.npmignore/.gitignore 等规则，决定哪些文件进入 ZIP。
5. 版本要求 ：至少需要 pnpm v7.0.0。可通过 pnpm --version 检查。

进阶：与 CI/CD 结合

在 GitHub Actions 或 GitLab CI 中，pnpm zip --standalone 常用于将构建产物打包为可直接部署的制品：

# .github/workflows/deploy.yml
- run: pnpm install
- run: pnpm zip --standalone --output build.zip
- uses: actions/upload-artifact@v3
  with:
    name: deploy
    path: build.zip

然后下载 ZIP 放到服务器上解压，执行 node index.js 即可启动。