版本发布流程¶

类型：rule（操作指南）描述：每次版本更新的标准动作 — 从「准备」到「发布」的完整流程 最后更新：2026-05-26 触发场景：用户说「发布 v0.x.y」/「构建新版本」/「打 zip」时 相关 wiki：docs/wiki/shared-queue-architecture.md

什么时候用¶

任何代码改动完成后，要构建测试包
准备发布 zip 给用户
命令式：用户说「上版本」「升 0.10.x」「打包」

标准操作步骤¶

1. 先做准备（不能跳）¶

# 1) 备份当前版本到 backup/v<当前版本>/
CUR=$(node -p "require('./package.json').version")
mkdir -p "backup/v${CUR}"
cp src/utils/scraper.ts src/utils/dynamic-scraper.ts src/utils/scraper-executor.ts \
   src/utils/storage-data.ts src/sections/settings/view/settings-view.tsx \
   "backup/v${CUR}/" 2>/dev/null || true
# 也可以备份全 src（更稳）：
# cp -R src package.json wxt.config.ts tsconfig.json "backup/v${CUR}/"

2. 改版本号（仅 package.json）¶

# package.json: "version": "0.10.x" → "0.10.(x+1)"

⚠️ 不要改 wxt.config.ts 里的版本，WXT 自动同步。

3. 改代码 + 构建验证¶

pnpm compile    # 1) 仅看「新增」的 TS 错误，已有历史错误不算
# 然后 step 2 改 package.json 版本号（如还没改）
pnpm build      # 2) 必须过（生产构建）→ dist-v2/chrome-mv3/

⚠️ 顺序铁律（v0.10.68 教训）：先 bump version，再 pnpm build。 WXT 在 build 时把 package.json 的 version 写进 dist-v2/chrome-mv3/manifest.json。顺序反了 → 用户加载扩展看到的还是旧版本号，commit message 写着新版本号但实际安装包还是旧的。

sanity check（commit 前必跑）：

PKG=$(node -p "require('./package.json').version")
MAN=$(node -e "console.log(JSON.parse(require('fs').readFileSync('dist-v2/chrome-mv3/manifest.json')).version)")
[ "$PKG" = "$MAN" ] && echo "✅ 同步：$PKG" || echo "❌ 不同步：package=$PKG  manifest=$MAN → 重跑 pnpm build"

注：不要直接 diff <(grep '"version"' …) <(grep '"version":"…"' …) — package.json 用 "version": "x" （冒号后有空格），manifest.json 用 "version":"x"（无空格），diff 必然不空但值可能已同步。必须解析 JSON 比较值。

4. 写开发日志（同时）¶

打开 development-log.md，在顶部新增一条：

## YYYY-MM-DD　v<旧版本> → v<新版本>　[一句标题]

### 用户反馈 / 改动目标
- ...

### 改动
- ...

### 验证
- pnpm build ✅ Xs
- pnpm compile ✅ 0 新错误

### 遇到的问题
- 问题：现象 → 原因 → 解决

### 注意点
- ...

5. 同步更新文档（按需）¶

概念误导类问题 → 补 更新规则.md 第七章 + 对应 docs/wiki/ 条目
首次使用新工具 / 新工作流 → 触发元规则，新建 docs/rules/<主题>.md
架构调整 → 必更新 docs/wiki/shared-queue-architecture.md 或新建条目

6. 浏览器实测¶

dist-v2/chrome-mv3/ 加载到浏览器： - 首次：chrome://extensions → 加载已解压扩展 → 选 dist-v2/chrome-mv3/ - 已加载：点扩展卡片上的「刷新」图标

7. 打包归档（可选，发布时做）¶

pnpm zip    # → dist-v2/laifaxin-chajian-ditu-<版本>-chrome.zip
# 归档到 test/（手动 cp）

必备前置¶

pnpm 已装（pnpm 11+ 需 pnpm-workspace.yaml 的 allowBuilds 放行 esbuild）
node ≥ 18

易错点¶

⚠️ 跳过备份：改完没法回滚 → 严格 step 1
⚠️ 跳过开发日志：下次自己看不懂为什么改 → 严格 step 4
⚠️ pnpm compile 红了就停：本项目有历史 TS 错误，看「新增」即可，看 pnpm build 是否过
⚠️ 改 wxt.config.ts（权限/host）后必须重新 build + 浏览器重载，否则不生效
⚠️ storage 字段不要轻易删：废弃只加 // deprecated 注释，删了破坏老用户数据
⚠️ build 在 bump version 之前跑了 → manifest 落后一版（v0.10.68 教训）： build 写入 dist-v2/chrome-mv3/manifest.json 的 version 来自 build 时的 package.json。正确顺序：改代码 → compile → bump version → build → commit。若顺序反了发现 manifest 版本号还旧 → 重跑一次 pnpm build 即可

完成后必做¶

development-log.md 顶部有本次记录
package.json version 已升
dist-v2/chrome-mv3/ 已构建
dist-v2/chrome-mv3/manifest.json 版本号 = package.json 版本号（sanity check 命令见 step 3）
触发了元规则的话，对应 docs/rules/ 或 docs/wiki/ 已更新
docs/rules/INDEX.md 同步（如果改了 rules）

示例：v0.10.14 完整流程¶

# step 1
mkdir -p backup/v0.10.13 && cp src/utils/scraper.ts ... backup/v0.10.13/

# step 2
# package.json: 0.10.13 → 0.10.14

# step 3
pnpm build  # ✅ 8.35s
pnpm compile  # ✅ 0 新错误

# step 4
# 写开发日志（包含 4 条用户反馈 + 改动 + 验证）

# step 5
# 概念误导 → 补 更新规则.md 第七章 表格新增 2 行