# customization-tools 定制工具包

云枢定制化项目工具包，解决定制项目中版本同步和定制包发布两大核心痛点。

# 解决什么问题

在云枢定制项目开发中，你会 fork 标品的 workspace 包进行修改（如 cloudpivot-form、cloudpivot-admin-core 等）。随着多人协作和版本迭代，会遇到以下问题：

定制包的版本号散落在各个 package.json 中，手动维护容易遗漏
多个包之间的依赖版本不一致，安装后运行报错
发布时不清楚哪些包需要发布，容易漏发或误发标品包

customization-tools 通过两个 CLI 命令自动化解决以上问题。

# 快速开始（完整使用教程）

# 前置条件

你已经拿到了云枢前端项目代码（如 frontend-8.6.9）
项目使用 yarn 作为包管理器
项目结构为 yarn workspace monorepo

# 第 1 步：安装 customization-tools

在项目根目录下安装（workspace 项目需要加 -W 参数）：

cd ~/your-project/frontend-8.6.9
yarn add customization-tools --dev -W

1
2

-W 表示将依赖安装到 workspace 根目录。不加此参数 yarn 会报错提示 "Running this command will add the dependency to the workspace root"。

# 第 2 步：配置 package.json

在项目根目录的 package.json 中添加以下配置：

{
  "scripts": {
    "preinstall": "node -e \"try{require('customization-tools').preinstall()}catch(e){}\"",
    "publish:custom": "publish-custom",
    "publish:custom:dry": "publish-custom --dry-run",
    "publish:custom:all": "publish-custom --all",
    "publish:custom:all:dry": "publish-custom --all --dry-run"
  },
  "customization": {
    "identifier": "你的项目标识符"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

preinstall 使用 || true 是为了兼容首次安装：此时 customization-tools 还未安装，命令不存在，|| true 确保不阻断 yarn install。后续安装时包已存在，会正常执行。

完整示例（以交行定制项目为例）：

{
  "name": "frontend",
  "version": "AI-Platform-v1.1.3-bankcomm",
  "private": true,
  "description": "云枢多包项目工程",
  "scripts": {
    "preinstall": "node -e \"try{require('customization-tools').preinstall()}catch(e){}\"",
    "publish:custom": "publish-custom",
    "publish:custom:dry": "publish-custom --dry-run",
    "publish:custom:all": "publish-custom --all",
    "publish:custom:all:dry": "publish-custom --all --dry-run",
    "dev:portal": "cd packages/portal && yarn run serve",
    "dev:admin": "cd packages/admin && yarn run serve",
    "build:portal": "cd packages/portal && yarn run build"
  },
  "customization": {
    "identifier": "ai-platform-bankcomm"
  },
  "workspaces": [
    "packages/*",
    "packages/builtin/*",
    "packages/plugin/*"
  ],
  "resolutions": {
    "cloudpivot": "1.1.2-ai-platform-bankcomm-2.3",
    "cloudpivot-admin-core": "1.1.2-ai-platform-bankcomm-2.4",
    "cloudpivot-form": "1.1.2-ai-platform-bankcomm-2.5"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 第 3 步：安装依赖（自动触发版本同步）

yarn install

执行 yarn install 时，preinstall 钩子会自动运行 sync-local-versions，你会看到类似输出：

[sync] 扫描 packages/ 目录...
[sync] 发现 23 个本地包
[sync] 识别定制标识符: ai-platform-bankcomm
[sync] 同步 cloudpivot-form: 1.1.2-ai-platform-bankcomm-2.4 → 1.1.2-ai-platform-bankcomm-2.5
[sync] 更新 resolutions: 新增 cloudpivot-form
[sync] 完成，共同步 3 个包

1
2
3
4
5
6

效果：

所有 package.json 中对定制包的依赖版本会统一对齐
resolutions 字段会自动维护（新增定制包、清理已恢复标品的包）
后续 yarn install 使用正确的版本安装

# 第 4 步：日常开发

正常开发，修改 packages/ 下的定制包代码即可。每次 yarn install 都会自动同步版本。

# 第 5 步：发布定制包

开发完成后，发布修改过的定制包到私有仓库。有两种发布模式：

# 默认模式 — 只发布未发布的版本

# 先预览，确认要发布哪些包
yarn publish:custom:dry

1
2

输出示例：

[publish-custom] 检测到 3 个定制包:

  ▶ cloudpivot-form@1.1.2-ai-platform-bankcomm-2.5
    registry: https://nexus01.authine.cn/repository/npm-cloudpivot/
    dist-tag: ai-platform-bankcomm
    状态: 未发布
    操作: [dry-run] 将会发布

  ▶ cloudpivot-admin-core@1.1.2-ai-platform-bankcomm-2.4
    状态: 已发布，跳过

1
2
3
4
5
6
7
8
9
10

确认无误后正式发布：

yarn publish:custom

# --all 模式 — 已发布的包自动升版后再发布

当所有定制包都已经发布过（比如要统一升一个新的定制版本），使用 --all 模式：

# 先预览，查看哪些包会升版
yarn publish:custom:all:dry

# 正式执行
yarn publish:custom:all

1
2
3
4
5

--all 模式流程：

遍历 resolutions 中的定制包，检查每个版本是否已发布
已发布的包自动升版（末位 +1，如 -2.3 → -2.4），仓库中不存在的包保持原版本
将新版本写入 resolutions 和本地包的 package.json
自动调用 sync-local-versions 同步所有交叉依赖
发布所有未发布的包
输出发布报告

默认模式 vs --all 模式： 默认模式适合日常开发中发布少量修改过的包；--all 模式适合定制版本迭代时批量升版发布。

# 发布说明（重要）

# 私有仓库地址

定制包发布地址为：https://nexus01.authine.cn/ (opens new window)（Sonatype Nexus 私有仓库）

# 是否需要发布？

场景	是否需要发布	说明
项目只在本地开发 / 单人使用	不需要	直接使用 workspace 本地包即可
团队多人协作，代码通过 Git 共享	不需要	每个人拉取代码后 `yarn install` 即可使用本地包
需要在 CI/CD 流水线中构建	需要	流水线环境没有本地源码，需从私有仓库安装
需要交付给客户或其他团队部署	需要	对方需要通过 `yarn install` 从仓库拉取定制包

# 不发布的情况

如果你的定制项目只是本地开发或团队通过 Git 协作，完全不需要执行 publish-custom。yarn workspace 会自动将 packages/ 下的本地包链接到 node_modules，无需从远端安装。

此时你只需要使用 sync-local-versions（版本同步）即可，确保所有包之间的版本引用一致。

# 需要发布的情况

当项目需要在 CI/CD 流水线中构建，或者需要交付部署包给其他人时，必须将定制包发布到私有仓库。因为这些环境不会拉取完整的 monorepo 源码，它们通过 yarn install 从 npm registry 安装依赖。

发布权限申请： 发布到 nexus01.authine.cn (opens new window) 需要申请权限。请联系运维或项目负责人开通你的账号对 npm-authine 仓库的发布权限，获取 auth token 后配置到 .npmrc：

//nexus01.authine.cn/repository/npm-authine/:_authToken=你申请到的token

# 配置详解

# customization.identifier

用于精确识别定制包的项目标识符。版本号格式为 主版本-标识符-定制版本，脚本通过此标识区分定制包和标品包。

项目	标识符	版本号示例
海大	`haid`	`8.3.49-haid-3.0`
交行	`ai-platform-bankcomm`	`1.1.2-ai-platform-bankcomm-2.3`

如果不配置，脚本会自动检测（统计 prerelease 标识符频次取最高频的），但建议始终显式配置以确保准确。

# resolutions

resolutions 是 yarn workspace 的特性，强制所有包使用指定版本。sync-local-versions 会自动维护此字段，正常情况下你不需要手动编辑。

# 目录结构

customization-tools/
├── bin/                          # CLI 入口
│   ├── sync-local-versions.js
│   └── publish-custom.js
├── lib/                          # 核心逻辑
│   ├── utils.js                  # 公共工具（JSON 读写、版本解析、workspace 扫描）
│   ├── sync.js                   # 版本同步逻辑
│   └── publish.js                # 定制包发布逻辑
├── index.js                      # 包入口
├── package.json
└── .npmrc

1
2
3
4
5
6
7
8
9
10
11

# 发布 customization-tools 本身

如果你需要更新这个工具包：

cd customization-tools/

# 预览发布内容
npm run release:dry

# 正式发布到私有仓库
npm run release

1
2
3
4
5
6
7

版本同步 →