企业官网建设流程全解析

ccstatusline-zh 是 Claude Code CLI 状态栏格式化工具 ccstatusline 的中文汉化版。本文完整记录这个汉化 Fork 与上游的同步方式：双版本号管理、同步基线、配置兼容策略、配置自动迁移以及更新检查机制，帮助使用者和开发者理解它的版本演进逻辑。

📌 项目定位：汉化界面，功能与上游完全一致

ccstatusline-zh 在保留上游全部功能（90 种组件、Powerline 主题、交互式 TUI 配置界面）的前提下，把所有用户可见的英文文本替换为中文。它当前同步至上游v2.2.32 / main@19c6665，中文包版本为2.2.33（见 README.md）。

💡 关键原则："后续同步以此提交为基线，中文包与上游版本号独立递增"（README.md）。每次同步都会把完整的上游提交哈希记入 README，保证任何人都能追溯汉化版到底基于哪一份上游代码。

🔢 双版本号策略：中文包独立递增

这是该 Fork 版本管理的核心设计，可以概括为三条规则：

1. 中文包版本号独立：npm 包ccstatusline-zh的版本号（package.json 中的2.2.33）不与上游版本绑定，中文包每次发布独立 +1。
2. 同步基线显式记录：README 开头明确写出"上次同步的完整上游提交：19c6665ecf14309a5ffcfcda5e31972833dd821a"（README.md），下次同步时以该提交为 diff 起点。
3. 同步提交语义化：仓库中每次上游同步对应一条chore: 同步上游 <基线哈希>风格的提交（例如85f2e17 chore: 同步上游 19c6665，补全中文化并发布 2.2.33），变更范围一目了然。

这样做的好处：用户通过ccstatusline-zh --version看到的是中文包版本，而 README 永远能回答"这份汉化版对应上游哪一版"，两边互不干扰。

🧩 配置兼容策略：内部标识符一律保持英文

汉化最容易踩的坑是"改了标识符导致配置失效"。ccstatusline-zh 的应对策略很克制：

• 只汉化展示文本：组件名称、描述、分类标签、TUI 菜单、对话框全部中文化；
• 标识符保持英文：settings.json 中的 widget type ID（如"model"、"git-branch"）保持英文不变，确保与上游版本的配置文件完全兼容（README.md）；
• 配置路径与上游共用：默认仍读写~/.config/ccstatusline/settings.json，Claude Code 侧仍是~/.claude/settings.json的statusLine对象，从上游切换到汉化版无需迁移任何文件。

仓库还附带了两份可直接导入的示例配置（版本 3、含exportedBy字段）：official-cc.json 与 personal-cc.json，方便快速体验"极简模式 + 短进度条"这类典型布局。

🔄 配置自动迁移：从 v1 到 v4 平滑升级

配置文件的 schema 带version字段，当前为v4（src/types/Settings.ts）。所有历史升级逻辑集中在 src/utils/migrations.ts，形成一条 v1 → v2 → v3 → v4 的迁移链：

• detectVersion()：无version字段的旧配置按 v1 处理；version存在但不是数字时判定为非法，拒绝按 v1 迁移（防止误重建丢数据）；
• migrateConfig()：逐级顺序应用迁移函数，直到达到目标版本；
• needsMigration()：加载前判断是否需要迁移。

其中 v3 → v4 是一次"语义收敛"：各组件零散的布尔隐藏开关（hideNoGit、hideZero、hideWhenEmpty等 9 个遗留键）被统一为按组件类型查表的metadata.hide状态列表（migrations.ts）。迁移时会先读取已写好的 hide 列表，再把旧开关合并进去，最后按固定顺序输出——保证用户旧配置升级后显示行为不变。

对用户来说这意味着：无论配置是三年前写的 v1 还是新格式，打开 TUI 都会被自动升级，不需要手工改 JSON。

📥 配置导入导出：差异预览 + 默认取消

同步策略同样体现在"跨机器搬运配置"上：

• 导出：TUI 导出配置时会写入exportedBy包版本字段（如 official-cc.json 中的2.2.22），接收方可据此判断来源版本；
• 导入：先做 schema 版本检查——比当前版本更新的配置直接拒绝，旧版本则走自动迁移；
• 新增 Shell 命令需确认：导入新增自定义命令时，ImportPreviewDialog 会完整列出新命令，且默认选中"取消"，防止误导入不可信命令；
• 机器相关字段隔离：applyImport()会过滤安装方式、schema 版本等机器本地元数据，替换模式恢复本机元数据，合并模式只改显式提供的设置（docs/DEVELOPMENT.md）。

这套机制保证了配置在不同版本、不同用户之间流转时既可用又安全。

🛡️ 损坏配置保护：非破坏性恢复

上游 v2.2.21 起引入的损坏配置保护在汉化版中原样保留，实现位于 src/utils/config.ts：

• 原子写入：配置先写同目录临时文件再 rename 覆盖，读方永远看到完整的旧文件或完整的新文件，不会读到"写一半"；
• 符号链接保留：settings.json 是软链接时，通过解析真实目标写入，不破坏链接本身；
• 坏配置不覆盖：invalid settings.json 加载失败时只返回内存默认值并记录getConfigLoadError()，TUI 显示警告徽标并要求确认后才允许覆盖，避免升级同步过程把坏配置"救活成默认值"。

这对 Fork 尤其重要：上游升级引入新 schema 时，用户旧配置即使解析失败也不会被悄悄改写。

🚀 版本固定与更新检查：不让用户被动跟随上游

汉化版把"上游发新版 = 用户被迫升级"这个问题，做成了可控流程：

构建环节的版本一致性由 scripts/replace-version.ts 保证：postbuild会把package.json的版本号替换进 dist 产物中所有__PACKAGE_VERSION__占位符，替换失败则构建报错退出，杜绝"包版本和运行版本不一致"。开发约束详见 docs/DEVELOPMENT.md（含 ink 补丁、React 精确锁版等说明）。

🧪 开发者实操：同步上游的完整步骤

如果你是接手维护的开发者，一次完整的上游同步大致是：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/cc/ccstatusline-zh cd ccstatusline-zh # 2. 安装依赖 bun install # 3. 以 README 记录的上游提交为基线，合入上游新提交并补全中文化 # 4. 本地验证：测试 + 类型检查 + 代码检查 bun test bun run lint # 5. 构建（postbuild 自动替换版本占位符） bun run build # 6. 用示例 payload 手动渲染验证输出 cat scripts/payload.example.json | bun run start # 7. 中文包版本号 +1，更新 README 同步基线，提交并发布

常用命令一览见 docs/DEVELOPMENT.md，手动渲染测试数据可用 scripts/payload.example.json。

✅ 总结

ccstatusline-zh 的上游同步可以归纳为一句话：版本号双轨、基线可追溯、配置零迁移。

• 中文包版本与上游版本独立递增，README 记录每次同步的完整上游提交哈希；
• 组件标识符、配置字段、纯值输出全部遵循上游契约，settings.json 与上游完全共用；
• 配置 schema 迁移、导入预览确认、损坏配置非破坏性恢复，保证用户跨越任何版本升级都无感且安全；
• 固定安装 + npm 仓库更新检查，让用户决定何时跟进上游。

正是这套策略，让一个汉化 Fork 既"长得像中文软件"，又始终与上游保持一步之遥。