深入 Claude Code 源码（一）：启动层——从 `claude` 回车到光标出现，经历了什么？

随着 AI 编程助手的普及，越来越多的开发者开始关注一个问题：这些工具的启动速度。一个需要等待 3 秒才能响应第一个字符的助手，和一个 300ms 内就绪的助手，用起来的感觉是天壤之别。Claude Code 作为一个运行在终端里的 AI 代理，在启动这件事上做了大量精心的工程设计——不是靠减少功能，而是靠更聪明的初始化策略。

本文是「深入 Claude Code 源码」系列的第一篇，带大家拆解 Claude Code 的启动层（Bootstrap Layer）。我们会从进程启动的第一行代码，一路追踪到终端光标出现，把中间经历的每一个关键环节都说清楚。

一、守门员：dev-entry.ts

Claude Code 的入口文件是 src/dev-entry.ts，但它并不是第一个被执行的业务逻辑——它是一个守门员。

大家可能会思考，一个正常的 Node.js/Bun 项目，直接 import 入口文件不就行了，为什么要多一个守门员？

这里需要说明一下背景：Claude Code 的源码是从 npm 发布包的 sourcemap 重建出来的。整个 src/ 目录有几百个模块，任何一个 import 路径写错，或者某个文件在重建过程中有缺失，程序运行到一半就会崩溃，而且错误信息往往藏在很深的调用栈里，极难定位。

dev-entry.ts 的做法是——在真正启动业务逻辑之前，先扫描所有相对 import 路径，验证每一个被引用的模块文件确实存在、可以被 Bun 的解析器找到。如果有任何一个缺失，它会打印出明确的诊断信息然后干净地退出，而不是让程序在某个角落里悄悄崩溃。

这就类似于航天器发射前的「发射前检查清单」——所有子系统依次确认 OK，才按下点火键。多一道检查的代价极低，但能拦住的问题却很真实。

二、最讲究顺序的文件：main.tsx

通过 dev-entry.ts 的校验之后，程序来到真正的核心启动文件：src/main.tsx。

这个文件的开头有一段注释，值得大家仔细读：

// These side-effects must run before all other imports:
// 1. profileCheckpoint marks entry before heavy module evaluation begins
// 2. startMdmRawRead fires MDM subprocesses (plutil/reg query) so they run
//    in parallel with the remaining ~135ms of imports below
// 3. startKeychainPrefetch fires both macOS keychain reads (OAuth + legacy
//    API key) in parallel
import { profileCheckpoint } from './utils/startupProfiler.js';
profileCheckpoint('main_tsx_entry');

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
startMdmRawRead();

import { startKeychainPrefetch } from './utils/secureStorage/keychainPrefetch.js';
startKeychainPrefetch();

这三行 import 加副作用调用，顺序严格不能乱。原因如下：

macOS 上读取 Keychain（钥匙串，用于存储 OAuth token 和 API key）需要调用系统 API，这个操作大约耗时 65ms。企业 MDM 策略的读取也需要启动子进程（plutil 或 reg query），同样需要数十毫秒。

如果等到所有模块 import 完成之后再做这两件事，它们会在关键路径上串行执行，白白增加启动延迟。工程师的思路是——在模块 import 还没执行完的时候，就把这两个慢操作的异步任务先发射出去。等后续业务逻辑真正需要这些数据时，它们早就在后台跑完了，取结果几乎不需要等待。

这就像一家餐厅，服务员在顾客点菜的同时就去厨房通知「备好常用食材」，不必等菜单确认了才开始备料。等顾客菜单出来，厨房已经准备好大半了。

三、功能开关：bun:bundle 的编译时黑魔法

继续往下看 main.tsx，大家会发现一个贯穿全文件的模式：

const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null;

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js')
  : null;

这里的 feature('COORDINATOR_MODE') 来自 Bun 的 bun:bundle 功能——它是编译时的死代码消除（Dead Code Elimination），不是运行时判断。

这里需要说明一个重要的区别：如果是运行时判断，代码会在 bundle 里，只是不执行；而编译时消除意味着当 feature('COORDINATOR_MODE') 为 false 时，那整个 require('./coordinator/coordinatorMode.js') 分支从最终产物里根本不存在——不是「存在但跳过执行」，而是「从未编译进去」。

Claude Code 有很多处于不同开发阶段的实验性功能：多智能体协调（COORDINATOR_MODE）、KAIROS 助手模式、历史记录 Snip（HISTORY_SNIP）、响应式压缩（REACTIVE_COMPACT）…… 这些功能可能对某些部署场景不可用，或者还在内测中。用 require() 而非顶层 import，配合 feature() 判断，Bun 就能在构建时把对应分支彻底从产物中剔除。

CLAUDE.md 里特别提醒大家保留这个模式：

Conditional imports via bun:bundle feature flags use require() to avoid circular dependencies — preserve this pattern.

四、完整启动流程

把 main.tsx 的初始化过程梳理下来，整个流水线如图所示：

各阶段的关键细节：

Phase 1 — 并行预热（import 阶段）

• profileCheckpoint('main_tsx_entry') 打上性能计时起点
• startMdmRawRead() 异步读取 MDM 企业策略（macOS 的 plutil，Windows 的注册表）
• startKeychainPrefetch() 并行发起两个钥匙串读取（OAuth token + 旧版 API key）

Phase 2 — Commander.js 命令解析

注册 claude 的所有子命令：claude login、claude config、claude mcp、claude --resume、claude -p "..." 等，并解析当前调用的命令行参数。

Phase 3 — 认证与权限初始化

• checkHasTrustDialogAccepted() 判断是否需要弹出信任确认对话框
• loadPolicyLimits() 加载企业策略限制（某些企业会禁用特定功能）
• initializeGrowthBook() 初始化功能开关服务，决定哪些实验性功能对当前用户开放

Phase 4 — 工具与服务装载

• getTools() 收集所有 53 个工具的定义
• getMcpToolsCommandsAndResources() 连接并枚举所有已配置的 MCP 服务
• getCommands() 收集所有 87 个 slash 命令

Phase 5 — UI 或执行路径选择

根据命令行参数决定走哪条路：-p 参数走 print 模式，无参数走 REPL 交互模式，作为 SDK 被调用时完全绕过这里。

五、三条执行路径的差异

大家可能还有疑问：SDK 模式和 print 模式具体有什么区别？

总体而言，三条路径的差异可以用下面这个表格来比较：

三条路径都依赖同一个底层引擎——QueryEngine，这也是为什么 Claude Code 能同时服务这么多不同场景，核心逻辑不需要重写。

六、启动延迟的工程取舍

整个启动过程，从 claude 回车到光标出现，在现代 Mac 上大约 300～500ms。其中绝大部分时间花在 TypeScript/Bun 模块解析上（约 135ms 的 import 评估，代码注释里明确标注了这个数字），业务逻辑本身非常轻。

这里有一个值得关注的工程权衡：print 模式（-p）里，recordTranscript() 这个写磁盘的操作被设计成 fire-and-forget（发射后不等待）：

// Bare/print mode: fire-and-forget. Scripted calls don't --resume after
// kill-mid-request. The await is ~4ms on SSD, ~30ms under disk contention

在 SSD 上只需要 4ms，但在磁盘压力大时可能到 30ms。对于 print 模式的脚本调用来说，这 30ms 意义不大，所以不阻塞。但交互模式下，为了保证 --resume 可靠，这里会等待写入完成。

这种「根据场景决定同步/异步」的细粒度取舍，在 Claude Code 的代码里随处可见。

本文带大家拆解了 Claude Code 启动层的核心设计，学习了：

1. dev-entry.ts 是进程启动前的完整性检查，确保所有模块路径可解析
2. main.tsx 的 import 顺序严格有序，通过并行预热把慢操作（Keychain、MDM）挪出关键路径
3. feature() + require() 是 Bun 的编译时死代码消除，让实验性功能从未出现在产物里
4. 启动最终分叉为交互、print、SDK 三条路径，都共享同一个底层 QueryEngine

接下来，我们将进入第二篇——查询引擎，也就是真正驱动 Claude 工作的心脏：query.ts 和 QueryEngine.ts。