企业官网建设流程全解析

• 人工智能
• AI Agent
• 浏览器控制
• AI 应用

nanobrowser 是一个基于 pnpm workspace 与 Turborepo 构建的开源 Chrome 扩展 monorepo，其版本号同时存在于根目录与各子包共 16 个package.json中（当前仓库内统一为0.1.13）。本指南围绕仓库根目录下的 UPDATE-PACKAGE-VERSIONS.md 展开，介绍如何通过一条命令完成所有包版本号的统一更新，并从 update_version.sh 源码层面剖析其校验、遍历与替换机制，帮助你安全、正确地执行版本发布前的同步操作。

一、为什么需要"一键更新版本"

nanobrowser 的仓库采用 pnpm workspace 管理多包结构，从 pnpm-workspace.yaml 可以看到：

packages: - "chrome-extension" - "pages/*" - "packages/*"

实际存在的package.json分布在根目录、chrome-extension/、pages/（content / options / side-panel）以及packages/（dev-utils、hmr、i18n、schema-utils、shared、storage、tailwind-config、tsconfig、ui、vite-config、zipper）共 16 个位置，且彼此版本号必须保持一致，否则会导致工作区内包依赖版本错乱。

更重要的是，浏览器扩展的 manifest 版本号直接来源于根package.json。在 chrome-extension/manifest.js 中：

const packageJson = JSON.parse(fs.readFileSync('../package.json', 'utf8'));

随后version: packageJson.version被写入 Manifest V3 配置（见 manifest.js）。也就是说，package.json的版本号直接决定了 Chrome Web Store 中扩展的发布版本。因此每次发版时，必须同步提升所有包的版本号，这正是update-version脚本存在的意义。

二、使用方法：一条命令完成全局版本更新

在仓库根目录执行（注意：脚本由 package.json 中的"update-version": "bash update_version.sh"注册为 pnpm 脚本）：

pnpm update-version <new_version>

版本格式必须为<0.0.0>三段式，例如：

pnpm update-version 0.2.0

执行成功后终端会输出：

Updated versions to 0.2.0

如果传入的版本号不符合三段式格式，脚本不会做任何修改，而是输出错误提示（详见下文源码分析）。

Windows 用户的注意事项

脚本依赖bash、find、grep、perl等 UNIX 命令，因此在 Windows 下必须使用支持 UNIX 命令的终端执行，例如Git Bash，不能直接在 CMD 或 PowerShell 中运行，否则会因找不到bash而报错。

输出信息解读

三、实现原理：读懂 update_version.sh

执行pnpm update-version实际调用的是根目录下的 update_version.sh，完整逻辑分三步：

1. 版本号格式校验

if [[ "$1" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then

脚本首先用正则表达式^[0-9]+\.[0-9]+\.[0-9]+$校验第一个参数$1：必须是「数字.数字.数字」结构（如0.1.13）。校验失败则进入else分支，输出格式错误提示并退出，不会触碰任何文件，保证错误输入下仓库版本号安全。

2. 遍历并替换所有 package.json

find . -name 'package.json' -not -path '*/node_modules/*' -exec bash -c ' current_version=$(grep -o "\"version\": \"[^\"]*" "$0" | cut -d"\"" -f4) perl -i -pe"s/$current_version/'$1'/" "$0" ' {} \;

这段命令做了三件事：

• find . -name 'package.json'：从根目录递归查找所有package.json，通过-not -path '*/node_modules/*'排除node_modules中的第三方包，确保只更新仓库自身的版本号；
• grep -o "\"version\": \"[^\"]*" | cut -d"\"" -f4：从每个文件中提取当前版本号字符串，作为后续替换的匹配目标；
• perl -i -pe "s/$current_version/'$1'/"：在原文件中进行原地（-i）替换，把当前版本号替换为命令行传入的新版本号。

3. 输出成功信息

echo "Updated versions to $1";

全部替换完成后打印Updated versions to <new_version>，与你看到的命令输出一一对应。

一个值得注意的实现细节

脚本是基于「当前版本号字符串」做精确替换，而不是直接把"version": "xxx"整体改写。这带来两点影响：

• 由于各包当前版本号统一，替换后仍能保持全局一致；
• 但该实现只替换字符串字面量，若package.json中某处恰好出现相同的数字字符串（例如依赖版本恰好与包版本相同），理论上也存在被一并替换的可能。因此在执行后，建议通过git diff核对改动范围，确认只修改了预期的"version"字段。

四、验证执行结果

脚本执行完成后，可以用以下命令快速验证所有包的版本号是否已统一：

grep -rn '"version"' --include='package.json' . | grep -v node_modules

正常输出应为 16 行且version值完全一致，例如当前仓库中全部为0.1.13：

./package.json:3: "version": "0.1.13", ./chrome-extension/package.json:3: "version": "0.1.13", ./pages/side-panel/package.json:3: "version": "0.1.13", ./pages/content/package.json:3: "version": "0.1.13", ./pages/options/package.json:3: "version": "0.1.13", ./packages/storage/package.json:3: "version": "0.1.13", ...

五、在发布流程中的位置

在 nanobrowser 的日常开发中，版本更新是发布链路的一环。根 package.json 定义了完整的工作流脚本：

• pnpm build：清理后由 Turbo 按依赖顺序构建全部包；
• pnpm zip：构建并打包成可分发产物（调用packages/zipper）；
• pnpm update-version <new_version>：发版前同步所有包版本号，随后pnpm build/pnpm zip生成的产物即携带新版本。

具体到浏览器扩展，由于 chrome-extension/manifest.js 的version字段直接引用根package.json的版本号，执行pnpm update-version之后，下一次构建产出的manifest.json会自动带上新版本，无需再手动修改 manifest 或重复更新其他包。

六、常见问题小结

结语

pnpm update-version是 nanobrowser 发版流程中成本最低、却最容易出错的环节。理解 update_version.sh 的校验、遍历与替换逻辑后，你既能安全地一键同步 16 个package.json的版本号，也能在遇到格式错误、Windows 环境差异等问题时快速定位原因。建议将其与git diff、grep -rn '"version"'结合使用，形成「执行 → 核对 → 构建 → 打包」的标准化发版闭环。

• 人工智能
• AI Agent
• 浏览器控制
• AI 应用