VPACKER

将 monorepo 中 CAS / Express / Midway / Vite 等包的构建产物复制并打成 zip 包，可以整合入 build 流程，便于部署

目录

• 安装
• 快速开始
  • 无需配置文件
  • 需要配置文件
• 配置文件
  • 字段说明
  • 包目录结构
  • 分组与参数
• 命令行
• 程序化调用
• 开发

安装

pnpm add -D @hnb-pkg/vpacker
# 或
npm i -D @hnb-pkg/vpacker

安装后可使用命令行：vpacker 或别名 vpk。

快速开始

以下功能无需配置文件

不依赖 vpk.config.*：用 -c / -e / -m / -v 直接指定要打包的包目录即可。
传入任一类型标记时，忽略自动发现的配置文件（等同 tsc 点名文件忽略 tsconfig）；若存在配置会提示「已忽略配置」。
（未传任何类型参数且又没有配置文件时，会提示如何用 init / -v 开始，而不是「未选择分组」。）

默认值

| 项 | 默认值 | 覆盖方式 | | --------------- | --------------------------------- | -------------------------------------- | | packages 根目录 | <当前工作目录>/packages | -P / --packages <dir> | | 输出目录 | <当前工作目录>/prod | -o / --outputs <dir> | | 配置文件 | 无（可选自动查找 vpk.config.*） | -C / --config（与类型标记互斥） | | 分组 | 不使用（无配置则无分组） | -g 需配置中的 groups；勿叠类型标记 |

包目录参数相对 packages 根（支持嵌套，如 dnxs/api）。-c/-e/-m/-v 用法相同，任选类型即可。

# 单包：packages/back → prod/back/ + prod/back.zip
vpk -v back

# 单仓打包：当前目录当作单个 Vite / Midway / … 项目（packages 默认为 cwd）
# → prod/<当前文件夹名>/ + prod/<当前文件夹名>.zip
vpk -v
vpk -m

# 改 packages / 输出目录
vpk -v back --packages ./pkgs -o ./dist-zip

# 多类型、多包、嵌套路径（传入任一类型参数后，只打这些类型，目录以 CLI 为准）
vpk -c cas -m dnxs/api -v dnxs/back front mobile/test/home

无配置文件时 不要用 -g/--group（分组在配置的 groups 里）；需要分组见下一节。

单仓说明

单仓（当前目录就是 cas / exp / mid / vite 包）时，类型参数可不跟目录：

| 写法 | 含义 | | ------------------------------------ | -------------------------------------------- | | vpk -v / vpk -m 等 | 打当前目录 | | vpk -v . | 同上（显式写出 .） | | cd ./test && vpk -m | 打其它目录上的单项目：先进入该目录再单仓打包 | | 配置 packages: "." + vite: ["."] | 配置文件版单仓（projects 必须是 ["."]） |

产物名用 当前目录 basename（不是 .），避免出现 prod/.zip。

packages: "." 不等于单仓。
若配置为 packages: "." 且 projects 是具名目录（如 vite: ["back", "front"]、mid: ["api"]），这是 packages 根为当前目录的多包仓库；执行 vpk 的打包范围为「配置中的全部项目」，不是「单仓（当前目录）」。单仓必须让某一类型的目录列表为 ["."]（或 CLI 裸类型标记 vpk -v）。

单仓与 monorepo（--packages / 配置里非 "." 的 packages，或 CLI 单仓再叠 monorepo packages 根）意图冲突，不能叠用。

禁止（会直接报错，避免歧义）：

| 写法 | 原因 | | ------------------------------------------------ | -------------------------------------------------------------- | | vpk --packages ./test -m | 单仓勿再指定 packages 根 | | vpk -m . --packages ./test | 同上（显式 . 仍是单仓；勿借 --packages 当项目路径） | | vpk --packages . -v | 同上；单仓不必写 --packages | | vpk -v back -m | 不能把「具名包」和「单仓」混在一次命令里 | | vpk -v -m | 单仓一次只能选一个类型 | | 配置 packages: "./pkgs" + vite: ["."] | 配置层同样冲突；单仓请用 packages: "."，或改 monorepo 具名包 | | vpk -g front -v / vpk -g front -v . | 分组与单仓互斥；单仓无法分组 | | vpk -g front -v front | 分组与类型点名互斥；请只留 -g 或只留 -v front | | vpk -C ./cfg.ts -v / vpk -C ./cfg.ts -v back | 显式 -C 与类型标记互斥；配置驱动勿叠 -c/-e/-m/-v |

monorepo 仍用 --packages + 具名目录（如 vpk -v back --packages ./pkgs），与单仓分开使用即可。

以下功能需要配置文件

# 生成配置文件
vpk init
# vpk init --force
# vpk init -o ./configs/vpk.config.ts
# vpk init --single          # 单仓（默认 vite）
# vpk init --single mid      # 单仓 Midway

# 未选择分组 → 打包 projects 中全部
vpk

# 按分组打包
vpk -g front
vpk --group default

# 类型点名（与 -g / 单仓互斥，勿叠用）
vpk -v front

配置文件

在项目根目录放置 vpk.config.*（也可用 -C / --config 指定）。
-C 与 -c/-e/-m/-v 互斥。仅传类型标记时会忽略自动发现的配置（并打日志说明）；配置驱动请用 vpk / vpk -g / vpk -C，不要叠类型标记。

全局安装 CLI 时：加载配置会把 @hnb-pkg/vpacker 映射到当前 CLI 所在包，因此 import { defineConfig } from "@hnb-pkg/vpacker" 运行时不必再在项目里安装依赖。若要在编辑器里获得类型提示，仍建议项目内 pnpm add -D @hnb-pkg/vpacker；也可以不写 import，直接 export default { ... }（defineConfig 只是类型辅助，运行时等价于原样返回）。

支持的文件名（按优先级）

vpk.config.ts → .mts → .cts → .js → .mjs → .cjs → .json

TypeScript 示例

// vpk.config.ts
import { defineConfig } from "@hnb-pkg/vpacker";

export default defineConfig({
  // packages 根目录，默认 <cwd>/packages
  packages: "./packages",
  // 输出目录，默认 <cwd>/prod
  outputs: "./prod",
  // 打包目标（值相对 packages；支持嵌套路径）
  projects: {
    mid: ["api"],
    vite: ["back", "front", "mobile"],
  },
  // 打包分组（成员须与 projects 中的字符串完全一致）
  groups: {
    "default": ["__all__"],
    "no-api": ["back", "front", "mobile"],
  },
});

字段说明

| 字段 | 类型 | 默认值 | 说明 | | ---------- | -------------------------- | ---------------- | ------------------------ | | packages | string | <cwd>/packages | monorepo packages 根目录 | | outputs | string | <cwd>/prod | 打包输出目录 | | projects | object | — | 按类型声明要打包的包目录 | | groups | Record<string, string[]> | — | 打包分组 |

projects 支持的类型：cas / exp / mid / vite，值可为 string 或 string[]。

每个字符串是相对 packages 的包目录路径，明确支持嵌套（如 dnxs/api、mobile/test/home），对应磁盘上的 packages/dnxs/api 等。
分组 / CLI 筛选时须使用与此处完全相同的字符串（不做末级目录名模糊匹配）。

包目录结构（按类型）

所有包都放在 packages（或你配置的路径）下。<name> 既可以是单层目录（api），也可以是嵌套路径（dnxs/api）。
打包前请先完成各包自身的构建；缺失的路径会静默跳过（除下方标明「必需」的项）。

cas（结构较固定）

按固定文件名从包根复制，不依赖 dist/：

packages/<name>/
├── utils/                 # 目录（建议有）
├── app.js                 # 必需语义上的入口
├── config.js
├── ecosystem.config.js    # PM2 进程配置
└── package.json

| 路径 | 说明 | | --------------------- | -------------------- | | utils/ | 工具目录，整目录复制 | | app.js | 应用入口 | | config.js | 配置 | | ecosystem.config.js | PM2 进程管理配置 | | package.json | 依赖与元信息 |

产物：prod/<name>/ + prod/<name>.zip（内容为上述项；缺文件则跳过）。

exp（Express，结构较固定）

先把 dist/ 内的文件铺到输出根目录，再追加运行相关文件：

packages/<name>/
├── dist/                  # 构建产物（内容会铺到 zip 根目录，不是保留 dist/ 这一层）
│   └── …                  # 例如 index.js、其它编译结果
├── assets/                # 静态资源目录
├── ecosystem.config.js    # PM2 等进程配置
└── package.json

| 路径 | 说明 | | --------------------- | ---------------------------------------- | | dist/ | 构建输出；复制的是其内部文件到产物根 | | assets/ | 静态资源 | | ecosystem.config.js | 进程管理配置 | | package.json | 依赖与元信息 |

产物：prod/<name>/ + prod/<name>.zip。
注意：与 Midway 不同，Express 不会在产物里再套一层 dist/ 目录名。

mid（Midway）

packages/<name>/
├── dist/                  # 必需，缺失会报错「未找到 dist 目录」
├── public/                # 可选，有则复制
├── bootstrap.js
├── ecosystem.config.js    # PM2 进程配置
└── package.json

| 路径 | 说明 | | --------------------- | ---------------------- | | dist/ | 必需，先构建再打包 | | public/ | 静态资源 | | bootstrap.js | 启动脚本 | | ecosystem.config.js | PM2 进程管理配置 | | package.json | 依赖与元信息 |

产物：

• prod/<name>/ + prod/<name>.zip（含 dist、public、bootstrap.js、ecosystem.config.js、package.json）
• 额外：prod/<name>-dist.zip（仅 dist 目录）

vite（前端静态站）

packages/<name>/
└── dist/            # 必需，缺失会报错「未找到 dist 目录」
    ├── index.html
    └── assets/
        └── …

| 路径 | 说明 | | ------- | --------------------------------------------------------- | | dist/ | 必需；将其内部文件复制到产物根（适合 Nginx 直出） |

产物：prod/<name>/ + prod/<name>.zip。
嵌套路径示例：vite: ["dnxs/back"] → 源 packages/dnxs/back，产物 prod/dnxs/back/ 与 prod/dnxs/back.zip。

嵌套路径示例

packages/
├── cas/
├── dnxs/
│   ├── api/          # mid: ["dnxs/api"]
│   └── back/         # vite: ["dnxs/back"]
├── front/            # vite: ["front"]
└── mobile/
    └── test/
        └── home/     # vite: ["mobile/test/home"]

import { defineConfig } from "@hnb-pkg/vpacker";

export default defineConfig({
  packages: "./packages",
  outputs: "./prod",
  projects: {
    cas: ["cas"],
    mid: ["dnxs/api"],
    vite: ["dnxs/back", "front", "mobile/test/home"],
  },
  groups: {
    // 须与 projects 中的字符串完全一致
    "default": ["__all__"],
    "no-api": ["dnxs/back", "front", "mobile/test/home"],
  },
});

错误示例（不要这样写）：分组里写 ["back", "home"] 不会按末级目录匹配，只会提示未匹配。

对照小结

| 类型 | 配置字段 | 是否强依赖 dist/ | 复制策略要点 | | ------- | -------- | ------------------ | ------------------------------------------------------------------------------- | | CAS | cas | 否 | 固定：utils + app.js + config.js + ecosystem.config.js + package.json | | Express | exp | 建议有 | dist 内容铺根 + assets + ecosystem.config.js + package.json | | Midway | mid | 是（否则抛错） | 保留 dist/；含 ecosystem.config.js；另打 *-dist.zip | | Vite | vite | 是（否则抛错） | 仅 dist 内容铺根 |

groups 的 value 为包目录名列表（须与 projects 中声明的字符串完全一致）：

• __all__：展开为 projects 中的全部包
• 其它字符串：按全名精确匹配（可跨类型；嵌套路径须写全，如 dnxs/back，不能只写 back）
• 匹配不上的成员：不中断打包，开始与结束时各提示一次

分组与参数

| 场景 | 行为 | | ---------------------------------- | --------------------------------------- | | 未传 -g/--group | 打包 projects 全部 | | -g default（组成员含 __all__） | 打包全部 | | -g front | 只打包组内列出的包（如 api、front） | | -g front default | 多个分组合并（并集） | | -v back front | 只打包指定 Vite 包（保留旧参数） | | -g 与 -v name / 单仓叠用 | 报错（三者互斥，见「单仓说明」） |

vpk
vpk -g front
vpk -g default
vpk -c cas -m api -v back front
vpk --config ./configs/vpk.config.ts -g front

命令行

vpk init

生成 vpk.config.ts：

vpk init
vpk init --force
vpk init -o ./configs/vpk.config.ts
vpk init --single
vpk init --single mid

| 选项 | 说明 | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | -f, --force | 覆盖已存在的配置文件 | | -o, --output <path> | 输出路径，默认 vpk.config.ts | | -s, --single [type] | 生成单仓配置（packages: "." + 类型 ["."]；默认 vite；类型可写 c/cas、e/exp/express、m/mid/midway、v/vite） |

单仓配置生成后直接 vpk 即可打包。

vpk version

显示当前 CLI 版本（与 -V / --version 相同）：

vpk version

vpk（打包）

根命令即打包，不必再写 pack：

将 CAS / Express / Midway / Vite 包的构建产物打成 zip

用法： vpk [options] [command]

选项：
  -V, --version     显示版本号
  -C, --config      指定配置文件路径（与类型标记互斥；默认查找 vpk.config.*）
  -P, --packages    packages 根目录（默认：<cwd>/packages；单仓时为 <cwd>）
  -o, --outputs     输出目录（默认：<cwd>/prod）
  -g, --group       按分组打包（可多选；未指定则全部）
  -h, --help        显示帮助信息

项目类型:
  -c, --cas         指定 CAS 包目录（不传目录则打包当前目录（单仓））
  -e, --exp         指定 Express 包目录（同上）
  -m, --mid         指定 Midway 包目录（同上）
  -v, --vite        指定 Vite 包目录（同上）

命令：
  init [options]    生成 vpk.config.ts 配置文件
  version           显示版本号

若仍写 vpk pack …，会提示改为直接使用 vpk [options]。

程序化调用

import { initConfigFile, loadConfig, resolvePlan, runCli } from "@hnb-pkg/vpacker";

await initConfigFile({ force: true });
await runCli({ group: ["front"] });

// 单仓打包当前目录（Vite）
await runCli({ vite: true });

const { config } = await loadConfig();
const plan = resolvePlan(config, { group: ["front"] });

开发

vp install
vp check
vp test
vp pack