版本管理最佳实践：快速拆解 Codex 插件 codex-plugin-cc 的 bump-version 脚本

版本管理最佳实践快速拆解 Codex 插件 codex-plugin-cc 的 bump-version 脚本【免费下载链接】codex-plugin-ccUse Codex from Claude Code to review code or delegate tasks.项目地址: https://gitcode.com/GitHub_Trending/co/codex-plugin-cccodex-plugin-cc 是一个让 Claude Code 用户直接调用 Codex 进行代码审查和任务委托的插件。这个项目的版本管理没有使用任何第三方发布工具而是靠一个不到 230 行的 Node.js 脚本 bump-version.mjs 完成改版本号 一致性体检两件事。今天我们就把它拆开看它为什么能一次改齐 4 个文件、6 处版本号以及哪些设计值得你抄走。为什么插件需要多处版本号同步一个 Claude Code 插件的版本号其实分散在多个清单文件里文件版本字段作用package.jsonversionnpm 包的版本基准package-lock.jsonversion、packages[].version锁文件版本plugins/codex/.claude-plugin/plugin.jsonversion插件自身声明的版本.claude-plugin/marketplace.jsonmetadata.version、plugins[codex].version市场元数据 插件条目版本手动逐个修改漏改一处就会导致市场显示的版本和实际发布的版本对不上。这个脚本的思路很朴素把全部 6 处版本字段集中登记然后用一条命令统一写入当前项目版本为 1.0.4。一键改齐所有版本号bump-version 命令在仓库根目录执行即可node scripts/bump-version.mjs 1.0.5package.json 中还把它注册成了 npm script日常更常用npm run bump-version 1.0.5执行时脚本会遍历 TARGETS 清单——一份文件路径 字段读写器的登记表——把新版本写回每个文件。两个细节值得注意幂等写入写入前后对比 JSON 字符串只保存真正发生变化的文件避免产生无意义的 diff运行后直接告诉你结果例如Set version metadata to 1.0.5: package.json, ...一眼确认改动了哪些文件。CI 健康检查check-version 命令光会改还不够还需要会查。脚本内置体检模式npm run check-version它会默认以package.json中的版本为基准逐一核对其余 5 处版本字段见 checkVersions发现不一致时会打印每一条不匹配并返回非零退出码失败信息直接点明是哪个文件的哪个字段落后了。把这个命令挂到 CI 里就能确保任何手动改动导致的版本漂移在合入前被拦截。设计拆解3 个值得抄的作业1️⃣ 表驱动的配置而不是写死的 if-else。TARGETS 把哪个文件的哪个字段抽象成一组get/set读写器。以后项目新增一个需要登记版本的清单文件只需在这张表里加一条记录bump 和 check 两条流程自动复用同一份登记表永远不会漏改。2️⃣ 先校验后写入。入口处的 semver 正则校验 会拒绝01.2、1.0这类不规范的版本号check 模式下连基准版本本身也要先通过 validateVersion。任何一步结构不对比如 marketplace 里找不到名为codex的插件条目都会以明确错误信息抛出而不是留下半成品文件。3️⃣ 显式失败 非零退出码。脚本末尾的 catch 块 把错误打印到 stderr 并设置退出码为 1——这对 CI 集成至关重要命令跑完不等于成功。测试策略用临时目录夹具验证同步版本脚本最怕只测了 happy path。tests/bump-version.test.mjs 的做法很典型makeVersionFixture 在系统临时目录里凭空造出一个包含 4 个清单文件的假仓库版本统一为 1.0.2测试完全不污染真实仓库通过 helpers.mjs 的run函数以子进程方式真实执行脚本验证的是命令行层面的完整行为第一条用例 断言 6 处版本全部被更新第二条用例刻意把package.json改成 1.0.3 制造漂移验证 check 模式能准确报出是哪个文件落后。运行入口就是 package.json 里的node --test tests/*.test.mjs只依赖 Node 18 内置测试框架零额外依赖。版本管理最佳实践清单 ✅从这个小脚本里可以提炼出 5 条通用实践单一事实来源 一处写入版本基准只认package.json所有派生字段由同一脚本同步写入前强校验语义化版本格式不合法就直接拒绝不给错误版本留入口提供只读的体检命令--check模式不改任何文件专供 CI 把关幂等地保存内容没变就不写盘让 git diff 保持干净版本与变更日志配套每次发版在 plugins/codex/CHANGELOG.md 中登记变更版本号才有含义。一个 200 多行的脚本同时做到了改得齐、查得出、测得准。如果你维护的项目也在多个清单里登记版本号这套登记表 双模式的思路值得直接搬走。【免费下载链接】codex-plugin-ccUse Codex from Claude Code to review code or delegate tasks.项目地址: https://gitcode.com/GitHub_Trending/co/codex-plugin-cc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考