Claude Code 源码本地构建方案

文档目的

本文档说明如何在当前仓库中，本地构建和运行 cc-scode/cluade-code 这份可开发工程，并解释为什么它是默认的本地构建目标。

结论先说

当前仓库里如果要做“本地构建 Claude Code 源码”，默认应选择：

  • cc-scode/cluade-code/

而不是：

  • cc-scode/claude-code-sourcemap/

原因是：

  1. cluade-code 具备完整工程结构，包含 package.json、src/、packages/、scripts/、tests/、docs/、build.ts 等。
  2. cluade-code 已明确提供开发、构建、测试命令，可直接用 Bun 运行。
  3. claude-code-sourcemap 更像是“从 npm 发布包 source map 中提取出来的证据/参考快照”，核心价值在溯源与对照，不是主开发入口。

目录角色说明

1. cc-scode/cluade-code

这是当前仓库中的主构建目标。

从已读取内容可确认：

  • package.json 中定义了 build、dev、dev:inspect、test、lint、format、health、docs:dev 等脚本。
  • build.ts 使用 Bun 的 Bun.build() 从 src/entrypoints/cli.tsx 进行打包。
  • 构建输出到 dist/，并包含构建后处理与资源复制步骤。
  • README 明确说明这是“源码版”可运行、可构建工程。

2. cc-scode/claude-code-sourcemap

这是参考快照 / 溯源材料。

它的关键用途是：

  • 保存 npm 包与 source map 还原结果
  • 用 extract-sources.js 从 package/cli.js.map 中恢复 restored-src/
  • 用来比对某段实现是不是来自发布产物

它不是本仓库中优先推荐的本地构建目标。

本地构建方案

方案 A：直接在 cluade-code 中开发与构建（默认方案）

这是最推荐的方式。

前置条件

  • 已安装 Bun
  • Bun 版本建议不低于仓库要求（package.json 中声明 bun >= 1.2.0，README 中建议使用较新版本）

进入目录

cd cc-scode/cluade-code

安装依赖

bun install

如果遇到 ripgrep 预编译包下载慢的问题，可按 README 提示设置：

DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1

然后再执行安装。

开发运行

bun run dev

说明：

  • 该命令会通过 scripts/dev.ts 启动开发版 CLI。
  • 开发模式会注入一组宏与 feature flag。
  • README 中提到，若看到特定版本号标记，说明跑的是源码开发版。

调试运行

bun run dev:inspect

适用于：

  • 需要让 VS Code 或其他调试器附加到 Bun 进程
  • 需要排查启动流程、REPL 初始化、工具调用链等问题

正式构建

bun run build

构建逻辑来自 build.ts，主要步骤包括：

  1. 清理 dist/
  2. 从 src/entrypoints/cli.tsx 开始进行 Bun 打包
  3. 启用 code splitting
  4. 注入宏定义与 feature 集合
  5. 对构建产物进行 import.meta.require 的 Node 兼容后处理
  6. 复制 vendor/audio-capture 到 dist/vendor/audio-capture
  7. 额外打包 scripts/download-ripgrep.ts

构建完成后，主入口位于：

  • cc-scode/cluade-code/dist/cli.js

构建产物特点

根据 README 与 build.ts：

  • 输出目录为 dist/
  • 主入口是 dist/cli.js
  • 会生成大量 chunk 文件，而不是单文件产物
  • 虽然主构建目标是 Bun，但构建后会补 Node 兼容逻辑，因此产物可以在 Node 环境中直接启动

方案 B：把 claude-code-sourcemap 当作溯源输入，而不是直接构建目标

如果你的目标不是开发功能，而是验证“源码从哪里来”，正确做法不是直接在 claude-code-sourcemap 上开发，而是：

  1. 保留 claude-code-sourcemap/package/cli.js.map
  2. 通过 extract-sources.js 恢复 restored-src/
  3. 将 restored-src/ 与 cluade-code/src/ 对照
  4. 需要开发时，回到 cluade-code/ 中完成实现与构建

相关命令：

cd cc-scode/claude-code-sourcemap
node extract-sources.js

常用命令汇总

以下命令都在 cc-scode/cluade-code/ 下执行：

# 安装依赖
bun install

# 开发运行
bun run dev

# 调试模式启动
bun run dev:inspect

# 正式构建
bun run build

# 全量测试
bun test

# 单测文件
bun test tests/integration/tool-chain.test.ts
bun test src/utils/__tests__/hash.test.ts

# lint / fix / format
bun run lint
bun run lint:fix
bun run format

# 健康检查 / 未使用检查
bun run health
bun run check:unused

# 本地文档预览
bun run docs:dev

推荐工作流

如果你的目标是“学习源码 + 能本地跑起来 + 能逐步改代码”，建议采用下面的顺序：

  1. 先阅读 days/day0/2026-04-04-source-comparison-report.md，理解 cluade-code 与 claude-code-sourcemap 的关系。
  2. 进入 cc-scode/cluade-code/，优先阅读其中自己的 CLAUDE.md。
  3. 执行 bun install。
  4. 先用 bun run dev 验证工程能否启动。
  5. 再用 bun run build 验证构建链是否完整。
  6. 需要校验实现来源时，再回头对照 claude-code-sourcemap/restored-src/。

风险与注意事项

  • 不要把 claude-code-sourcemap/ 误当成主开发工程。
  • cluade-code 中有一些 feature-gated、stub 或还原代码，调试时应结合其内部 CLAUDE.md 和 docs/ 一起看。
  • 构建依赖 Bun，不建议先按传统 Node 工程思路处理。
  • 构建产物是多文件 chunk 结构，排查问题时不要只盯着 dist/cli.js。

最终建议

对于本仓库，“源码本地构建”的标准方案就是：

  • 以 cc-scode/cluade-code/ 作为主工程
  • 用 Bun 安装、运行、构建、测试
  • 把 cc-scode/claude-code-sourcemap/ 作为来源校验和差异分析材料

这也是当前最符合仓库结构和已有资料的一条路径。