CLI on acye's blog

团队 CLI 功能清单：每个功能的难点与简单解法

Sat, 12 Sep 2026 15:00:00 +0800

这篇把一个团队 CLI 该有的功能列全，每个功能一句话点出难点，再给一个简单有效的解法。代码均脱敏。

功能全景

功能	难点	解法
命令注册分发	命令多了硬编码不可扩展	约定式 registry：`command/<name>/index.js` 导出 `main`
参数解析	别名/布尔/数组混	`minimist` + 集中 `alias` 表
脚手架 create	模板与依赖版本耦合	`git clone` 模板 + `npm view` 拉最新版本写入 deps
构建编排 build	统一下发配置又不改业务码	文本改写 `vue.config.js` + 环境变量重定向
构建期 HTML 注入	四类能力逐项目手抄	`html-webpack-plugin` 钩子 + cheerio
lint 治理	规则统一 + 严重度切换	CLI 自带 eslintrc + env 切 mode
git 钩子	规范靠人	yorkie `gitHooks` 物化 + `pre-commit` 校验
依赖安装	私有源 + 版本漂移	私有 registry + `--lock` 剥 `^/~`
自更新	频繁检查拖慢启动	本地 `checkdate` 周节制流 + 手写 semver
遥测	上报阻塞主流程	`detached + unref + try/catch`
本地配置	污染宿主项目	`~/.team-cli/` 目录
终端体验	长任务无反馈	`ora` spinner + `colors` + `inquirer`
跨平台	POSIX 工具 Win 失败	`shelljs` / 纯 Node API 替代（残留脆弱点见末尾）
CI 集成	仓库带 dist + 小程序闭环	dist 保留式提交 + `miniprogram-ci` + 群消息通知

下面挑最关键的展开。

命令注册：约定优于配置

难点：命令越来越多，if (cmd === 'x') 式分发无法扩展，加命令要改主调度。

解法：约定 command/<name>/index.js 导出 main(options) 即完成注册，启动时按目录自动发现并校验 typeof main === 'function'，别名集中在 alias.js。

#!/usr/bin/env node
const argv = require("minimist")(process.argv.slice(2));
const alias = require("./command/alias");

function loadModule(name) {
  const sub = alias[name] || name;
  try {
    const mod = require(`./command/${sub}`);
    if (typeof mod.main === "function") return mod;
  } catch (e) {}
}

invokeCommand(argv._[0], argv);

// alias.js —— 别名集中在一张表，加命令零侵入主调度
module.exports = {
  h: "help",
  dev: "serve",
  i: "install",
  up: "update",
  v: "version",
  hook: "githook",
};

构建编排：文本改写替代 webpack-chain

难点：要给所有业务项目统一下发骨架屏、监控、埋点、CDN 分片，但不能要求每个项目用同一套 webpack-chain，更不能改业务代码。

解法：对项目 vue.config.js 做文本级改写，生成临时 build.override.config.js，再用 VUE_CLI_SERVICE_CONFIG_PATH 环境变量让 vue-cli-service 加载改写后的配置而非原文件。

flowchart TD
  A["读 cli.config.json + 默认配置"] --> B["生成 requireStr/pluginStr"]
  B --> C["读项目 vue.config.js 并 deleteNote 剥注释"]
  C --> D{"configureWebpack 形态"}
  D -- 函数 --> E["split('configureWebpack') 切串<br/>在首个 { 注入 config.plugins.push()"]
  D -- 对象 --> F["split('plugins:') 切串<br/>在 [ 处注入 new X(),"]
  E --> G["写 build.override.config.js"]
  F --> G
  G --> H["设 VUE_CLI_SERVICE_CONFIG_PATH"]
  H --> I["spawn vue-cli-service build"]
  I --> J["结束 删临时文件并透传退出码"]

核心是 configureWebpack 有函数和对象两种形态，用字符串切分而不是 AST处理：

// 函数形态：在 configureWebpack 函数体的首个 { 后注入 plugins.push
function setConfigWebpackStr(data) {
  const paramsName = getConfigParame(fileConfig, "configureWebpack"); // 还原形参名
  const newPluginStr = pluginStr.replace(/.plugins/, `${paramsName}.plugins`);
  if (data.indexOf("configureWebpack") > -1) {
    const [before, after] = data.split("configureWebpack");
    const inserted = after.replace(/{/, `{${newPluginStr}`); // 首个 { 注入
    return `${requireStr}${before}configureWebpack${inserted}`;
  }
  // 未配置 configureWebpack：在 module.exports 首个 { 注入整个钩子
  const [before, after] = data.split("module.exports");
  const inserted = after.replace(
    /{/,
    `{configureWebpack: ${paramsName} => {${newPluginStr}},`,
  );
  return `${requireStr}${before}module.exports${inserted}`;
}

对象形态类似，沿 plugins: 切，在 [ 处注入 new X(),。改写完写文件、设环境变量、起子进程：

fs.writeFileSync("build.override.config.js", rewritten);
process.env.VUE_CLI_SERVICE_CONFIG_PATH = "build.override.config.js";
const command = spawn("npx", ["vue-cli-service", ...argv._], {
  stdio: "inherit",
});
command.on("close", (code) => {
  deleteFile("build.override.config.js"); // 清理临时文件
  code === 0 ? spinner.succeed("成功") : spinner.fail(`失败: ${code}`);
  process.exit(code);
});

脆弱点（诚实说）：字符串改写依赖标识符与花括号位置，deleteNote 剥注释时含 // 的字符串或正则可能被误伤。解法是给一个 --base 透传作为逃逸舱，脆弱项目直走原生构建。本地跑通多项目构建兜底。

构建期 HTML 注入

难点：首屏白屏、前端监控、性能埋点若逐项目手抄，升级一次要改 N 个仓库。

解法：四个插件挂 html-webpack-plugin 的 before-html-processing / after-html-processing 钩子，用 cheerio 改 HTML。以页面耗时埋点为例：

class injectTime {
  apply(compiler) {
    compiler.plugin("compilation", (compilation) => {
      compilation.plugin(
        "html-webpack-plugin-after-html-processing",
        (data, cb) => {
          let html = data.html;
          html = html.replace(
            "</title>",
            "</title><script>window.__page_start__ = Date.now();</script>",
          );
          html = html.replace(
            "</body>",
            "<script>window.__page_end__ = Date.now();</script></body>",
          );
          data.html = html;
          cb && cb(data);
        },
      );
    });
  }
}

监控注入（injectBl）读 cli.config.json 里的监控 PID，没配 PID 就直接 return 不注入，避免无监控项目被注入空探针；挂的是 before-html-processing，把探针文件里的占位 PID 替换成真实 PID 后塞进 #inject 节点：

class injectBl {
  apply(compiler) {
    let pid;
    try {
      if (fs.existsSync("cli.config.json")) {
        pid = JSON.parse(fs.readFileSync("cli.config.json")).monitorPid;
        if (!pid) return; // 未配置 PID，跳过注入
      } else {
        return;
      }
    } catch (e) {
      return;
    }

    compiler.plugin("compilation", (compilation) => {
      compilation.plugin(
        "html-webpack-plugin-before-html-processing",
        (data, cb) => {
          const $ = cheerio.load(data.html);
          let probe = fs.readFileSync(probeFile).toString();
          probe = probe.replace(/<placeholder-pid>/, pid);
          $("#inject").text(probe);
          data.html = $.html();
          cb && cb(data);
        },
      );
    });
  }
}

四类能力（骨架屏/监控/埋点/CDN 分片）各自一个插件，按需在 cli.config.json 的 plugins 数组里开关。升级时只升 CLI，全项目生效。

git 钩子：规范即拦截

难点：企业邮箱、未解决冲突、master 严格 lint 靠人盯不住。

解法：utils/git.js 提供 git plumbing 只读层，githook 命令提供执行层；通过 yorkie 的 gitHooks 字段把钩子物化进 .git/hooks。

function preCommit(args) {
  const branch = getCurrentBranchName().toLowerCase();
  const files = getGitDiff();
  const eslintFiles = files.filter((f) =>
    [".js", ".vue", ".ts"].includes("." + getFileFormat(f).extend),
  );

  checkGitEmail(); // 邮箱域白名单
  const conflicts = checkConflicts(files);
  if (conflicts.length > 0) {
    Logger.log("未解决冲突，请修复后再提交");
    process.exit(1);
  }
  eslint({ isProd: branch === "master", files: eslintFiles });
}

function checkGitEmail() {
  const email = getGitInfo("user.email").toLowerCase();
  const reg = /@company\.com$/i;
  // ci-bot 为编译账户，允许提交
  if (email !== "ci-bot" && !reg.test(email)) {
    Logger.log("请用公司邮箱: git config user.email name@company.com");
    process.exit(1);
  }
}

master 分支按 prod 严格挡 console/debugger，其他分支 test 放行——分支即严重度。package.json 里物化钩子：

"gitHooks": {
  "pre-commit": "team-cli githook pre-commit",
  "pre-push": "team-cli githook pre-push"
}

自更新：周节制流

难点：每次命令都 npm view 查远程版本，启动慢；不查又版本散落。

解法：本地存一个 checkdate 文件做周节制流，一周查一次远程，结果缓存本地；版本比较手写 3 段 semver，零依赖。

const dayStep = 7;
function isChecked() {
  const checkDateStr = readLocalConfig("checkdate");
  if (checkDateStr) {
    if (compareAsc(new Date(), new Date(checkDateStr)) < 0) return true; // 本周已检查
    saveCheckDate();
    return false;
  }
  saveCheckDate();
  return false;
}

function compareVersion(a, b) {
  const pa = a.split("."),
    pb = b.split(".");
  for (let i = 0; i < 3; i++) {
    const na = +pa[i],
      nb = +pb[i];
    if (na > nb) return 1;
    if (nb > na) return -1;
  }
  return 0;
}

已检查过的周期内读本地缓存的远程版本，省掉 npm view 网络请求；只有跨周才重新查远程。

依赖安装：私有源 + 锁版本

难点：私有源要内网/VPN，^/~ 导致各机版本漂移。

解法：私有 registry + --lock 剥掉 ^/~ 锁死。装完读 package.json，把目标包的 ^ 前缀去掉写回：

function lockDepsVer(depList) {
  const pkg = readPackageJSON();
  depList.forEach((dep) => {
    const v = pkg.dependencies[dep];
    if (v) pkg.dependencies[dep] = v.replace(/^[\^~]/, "");
  });
  writePackageJSON(pkg);
}

其余功能一句话

遥测：spawn 起 curl，detached + unref 脱离父进程，try/catch 兜底，上报失败不影响命令。
本地配置：~/.team-cli/ 目录存 checkdate、version，不碰业务项目。
终端体验：ora 给 spinner，colors 给颜色，inquirer 给交互式选择。
CI 集成：push 把 dist 一起提交（仓库带产物）；mpbuild 跑 miniprogram-ci 上传微信后台 + 生成预览二维码 + 群消息卡片通知，只在 master + prod 触发真上传，防测试产物误传正式。

小程序构建闭环：mpbuild

mpbuild 是 CLI 里最长的命令，把"构建 → 压缩 → 上传 → 通知"串成一条：

flowchart LR
  A["taro build --type weapp"] --> B["tar -zcvf 压缩 dist"]
  B --> C{"master + prod?"}
  C -- 是 --> D["miniprogram-ci.upload<br/>上传微信后台"]
  C -- 否 --> E["仅生成预览二维码"]
  D --> F["生成预览图片"]
  E --> F
  F --> G["上传图片到 OSS"]
  G --> H["发群消息卡片<br/>含二维码/下载链接/commit"]

关键防呆：只有 branch 含 master 且 env=prod（或显式 --isUpLoad=true）才真上传微信后台，其他情况只出预览二维码，避免测试包误传正式。通知卡片里带分支、环境、构建者、commitId、压缩包下载链接。

脱敏提醒：这一步涉及群机器人凭证和上传密钥。源码里这些是明文 app_id/app_secret——绝不能写进文章，真实环境必须走环境变量或 CI Secret 注入，不要硬编码进仓库。

跨平台：POSIX 依赖的取舍

为什么这么做：团队开发机假设全是 macOS / Linux，rm -rf、tar -zcvf、which、ln -s、cp -r 这些 POSIX 命令开箱即用，写起来最快，没必要引第三方库。在这个前提下，没问题。

前提变了才出事：一旦团队进了 Windows 机器，或 CI 跑在 Windows runner 上，这些调用直接挂。这是"环境假设"换来的便利的代价。

扩展跨平台：用 shelljs（shell.rm('-rf', x)）或纯 Node API（fs.rmSync(x, {recursive:true, force:true})）替代 POSIX 调用。

	好处	坏处
`shelljs`	贴近 shell 写法、改动小	多一个依赖、部分命令比原生慢
纯 Node API	零依赖、最快、最可控	写法啰嗦、`tar` 压缩等无标准库等价物需引包

取舍：团队环境稳定且封闭 → POSIX 可接受；团队有跨系统可能或要开源 → 一开始就用纯 Node API，tar 这类用 archiver 之类的包补齐。

CLI 不是前后端项目：它和前端/后端项目的本质差异与设计要求

Sat, 12 Sep 2026 14:30:00 +0800

很多人觉得"会写前端或后端就能写 CLI"。真写起来处处踩坑，因为 CLI 和前端项目、后端项目的运行模型都不同。这篇讲差异，以及差异推导出的设计要求。

本质差异：CLI vs 前端 vs 后端

flowchart TB
  subgraph FE["前端项目"]
    F1["URL 或用户交互进"] --> F2["渲染"] --> F3["DOM 出"]
    F3 -.跑在浏览器.-> F1
  end
  subgraph BE["后端项目"]
    B1["HTTP 请求进"] --> B2["处理"] --> B3["HTTP 响应出"]
    B3 -.常驻进程.-> B1
  end
  subgraph CLI["CLI 工具"]
    C1["argv 进"] --> C2["解析加执行"] --> C3["stdout 加退出码"]
    C3 -.退出.-> C4["进程结束"]
  end

维度	前端项目	后端项目	CLI 工具
运行方式	构建产物跑浏览器	常驻进程	单次执行后退出
入口	`index.html` + `main.js`	`server.listen`	shebang + `bin` 全局命令
输入	用户交互 / URL	HTTP 请求体	argv 命令行参数
输出	DOM / 渲染	HTTP 响应	stdout/stderr + 退出码
依赖位置	项目 `node_modules`	项目 `node_modules`	全局 / CLI 自身 `node_modules`
用户	终端用户	终端用户 / 其他服务	开发者 / CI
副作用	DOM / 本地存储	数据库 / 缓存	文件系统 / git / 子进程
升级方式	重新部署	部署发版	自更新命令
失败标准	白屏 / 报错	5xx / 超时	退出码非 0

差异详解

入口与分发

前端靠 index.html 加载 JS，后端靠 listen 等请求；CLI 靠 shebang 把自己变成命令，靠 bin 字段做全局软链，靠约定式分发按目录加载子命令：

#!/usr/bin/env node
const argv = require('minimist')(process.argv.slice(2));
const alias = require('./command/alias');

function loadModule(name) {
  const sub = alias[name] || name;        // 别名转换
  try {
    const mod = require(`./command/${sub}`);
    if (typeof mod.main === 'function') return mod;  // 约定：导出 main 才算合法命令
  } catch (e) {}
}

invokeCommand(argv._[0], argv);

package.json 里 "bin": { "team-cli": "index.js" } + 全局安装 = 终端任意位置可调。这是 CLI 和前后端项目的分界。

输入输出：argv 与退出码

前端输入是用户交互，后端是 JSON body，CLI 是 process.argv——要自己解析布尔、数组、别名。输出不只是文字，退出码是契约：前端靠白屏判断、后端靠 5xx 判断，CLI 靠 exit code——CI 据此判成败，console.log 喊得再响也没用：

command.on('close', code => {
  if (code === 0) spinner.succeed('成功');
  else { spinner.fail(`失败: ${code}`); process.exit(1); }
});

进程模型：编排子进程

前端的副作用在 DOM，后端在数据库，CLI 的副作用大多靠子进程完成（spawn 跑 vue-cli-service、git、npm、taro）。要处理 stdio: 'inherit' 共享输入输出、close/error 事件、超时、退出码透传。前后端项目很少碰这些。

依赖边界

前后端依赖都装在项目 node_modules，和项目同生共死；CLI 全局安装，依赖装在自己 node_modules，不能污染宿主业务项目。所以本地配置要放 ~/.team-cli/，不是项目目录；临时文件用完即删。

副作用：必须幂等可回滚

前端改坏 DOM 刷新就好，后端接口失败可以重试；CLI 改坏开发者本地的 package.json / vue.config.js 是事故。所以写文件前读、生成临时文件用完删、可逆操作优先。改完 package.json 写回前先读再改，不要整文件覆盖丢字段。

跨平台

前端产物跑浏览器无所谓系统，后端跑在 Linux 服务器也无所谓；CLI 跑在开发者机器——rm -rf、tar、ln -s、which、cp -r 这些 POSIX 工具在 Windows 下直接挂。Windows / macOS / Linux 都得活。

flowchart TD
    A["团队开发机环境"] --> B{"全员 macOS/Linux?"}
    B -- 是 --> C["POSIX 命令直接用<br/>写得快 零依赖"]
    B -- 否 --> D["cmd/PowerShell 会挂<br/>需 shelljs 或纯 Node API"]
    C --> E["前提不变 = 一直能跑"]
    D --> F["扩展跨平台"]

版本治理

前端版本由部署控制，后端版本由发版控制；CLI 散落在每台开发机，得自己管升级、锁版本、向后兼容。

设计要求

从差异反推 CLI 该满足的要求：

要求	为什么	落地
约定优于配置	降低学习成本	`command/<name>/index.js` 导出 `main` 即注册
零配置可用	新人开箱即跑	默认值兜底，缺配置走 `defaultConfig`
可扩展	命令会越加越多	约定式 registry，不改主调度加新命令
启动要快	慢 = 体验差	检查更新用周节制流，不每次请求远程
副作用可回滚	别弄坏宿主项目	临时文件用完删，写前备份
退出码语义	CI 靠它判成败	成功 `exit(0)`，失败 `exit(非0)`
跨平台	开发机系统杂	慎用 POSIX，用 `shelljs` / 纯 Node API 替代
可观测	治理要数据	遥测上报用法，`try/catch` 不阻塞
可自更新	版本不能散落	私有源 + 周节制流 + `upgrade` 命令
不污染宿主	全局工具要克制	本地配置放 `~/`，依赖放自身 `node_modules`

对开发者的要求

写 CLI 的人比写业务多一层：要熟 child_process 编排、跨平台 POSIX 坑、退出码契约，心态上把"改坏开发者本地"当事故——一切操作幂等可回滚。

下一篇逐个功能拆解难点和解法。

从 Unix 哲学到团队工程化：CLI 的演进与自建 CLI 的价值

Sat, 12 Sep 2026 14:00:00 +0800

CLI 不是新东西，但"团队自建 CLI"是前端工程化成熟到一定阶段才会出现的基础设施。这篇讲清楚 CLI 怎么演进到今天，以及一个团队 CLI 到底能替你省掉多少"靠人"的事。

CLI 的历史演进

flowchart LR
    A["Unix 小工具与管道"] --> B["shell/make 任务编排"]
    B --> C["npm bin 把 JS 变命令"]
    C --> D["框架 CLI vue-cli/CRA/ng"]
    D --> E["团队 CLI 规范与能力下沉"]

Unix 时代：一个程序只做一件事，用管道 | 组合。ls | grep | wc 就是最早的"组合优于集成"思想。

脚本时代：make、shell 把零散命令编成任务，但跨平台差、依赖系统环境。

Node 早期：package.json 的 bin 字段把一个 JS 文件变成全局命令，#!/usr/bin/env node 这行 shebang 是分水岭——从此命令可以用 JS 写，跨平台、依赖可管理。yeoman、bower 是这一代代表。

框架 CLI 时代：vue-cli、create-react-app、@angular/cli 把"脚手架 + 构建 + 开发服务器"打包成一个入口。CLI 不再只是"跑脚本"，而是"项目全生命周期的入口"。

团队 CLI 时代：框架 CLI 解决"通用脚手架"，但每个公司都有私有源、私有规范、私有监控。团队 CLI 把这些"只属于这个团队"的东西下沉成一条命令。下文以一个真实团队 CLI（下称 team-cli）为例。

团队 CLI 的价值：把"靠人"变成"靠程序"

团队工程化最大的敌人不是技术难度，是"规范写在 wiki 里，没人看也没人执行"。CLI 的本质价值：把规范从文档变成可执行程序。

痛点	靠人的结果	CLI 下沉后
提交规范	review 时才发现邮箱错、带冲突	`pre-commit` 钩子自动拦截
构建能力统一	每个项目手抄骨架屏/监控	构建期自动注入，业务零改码
依赖版本	`^` 导致各机版本漂移	`--lock` 剥掉 `^/~` 锁死
CLI 版本散落	有人用 v1 有人用 v3	周节制流自更新提示
谁在用	不知道	遥测上报用法
新项目脚手架	复制老项目改半天	`create` 拉模板 + 自动解析依赖版本

规范下沉：钩子即策略

邮箱域白名单、未解决冲突、master 分支严格 lint——这些规则写进 pre-commit，违规直接 process.exit(1)，比任何 wiki 都管用。规范不再是"建议"，而是"不通过就提交不了"。

flowchart LR
    Dev["开发者 git commit"] --> Hook["pre-commit 钩子"]
    Hook --> E["检查邮箱域"]
    Hook --> F["检查未解决冲突"]
    Hook --> L["分支决定 lint 严格度"]
    L -- "master" --> Strict["禁 console/debugger"]
    L -- "其他分支" --> Warn["warn 放行"]
    E -->|不合规| X["exit(1) 拦截"]
    F -->|有冲突| X

master 分支按 prod 严格挡 console/debugger，其他分支 warn 放行——分支即严重度。

能力统一下发：构建期注入

骨架屏、前端监控、性能埋点、CDN 分片，四类运行时能力在构建期注入 index.html，业务代码一行不改。升级时只升级 CLI，所有项目同时生效——这是"集中管控"在工程化里最优雅的落地。

环境收敛

私有源 registry、yarn v1 版本约束、依赖版本锁定——一个命令把"环境一致性"从口号变成强制。新人入职不再需要一份"环境配置文档"。

自更新与遥测

function reportUsage(argv) {
  try {
    const url = 'http://<report-host>?type=cli-usage';
    const info = {
      user: getGitInfo('user.name'),
      branch: getCurrentBranchName(),
      ip: ip.address(),
    };
    const cp = spawn(`curl -s -X POST -d '${JSON.stringify(info)}' ${url}`, {
      timeout: 2000, detached: true, shell: true, stdio: 'ignore',
    });
    cp.unref();
  } catch (err) {}
}

detached + unref 让上报脱离父进程，try/catch 保证遥测失败也不影响命令执行。知道"谁在用、用哪个版本"，治理才有抓手——否则你连该不该强制升级都不知道。

什么时候该自建

团队项目数 > 5，且共享私有源、私有规范、私有监控 → 该建
只有 1-2 个项目，规范能靠 ESLint + husky 解决 → 不用建，框架 CLI 够了
框架 CLI（vue-cli/vite）能力够用，缺的只是几个私有命令 → 考虑做插件而非全新 CLI

自建 CLI 的成本不在写命令，在长期维护：版本治理、跨平台、向后兼容。门槛在下一篇——它和普通 Node 项目的本质差异。