Claude Code 启动序列

当你在终端里敲下 claude 时，CLI 并不是立刻把提示符画出来。它会先经过一条多阶段启动链：入口脚本处理快速路径，主函数装配运行环境，setup() 初始化会话状态，最后才把 Ink 驱动的 REPL 渲染出来。

理解这条链路的价值有三个：你能解释首屏延迟来自哪里、能更快定位启动期异常，也能看懂为什么源码里要把某些 I/O 提前并行化，而不是等到真正需要时再顺序执行。

下图跟踪了从进程进入到第一次渲染的确切调用顺序：

第 1 阶段 — CLI 入口点 (cli.tsx)

cli.tsx 的目标不是“做很多事”，而是“尽量少做事”。它先处理那些无需完整启动链的快速路径，再把剩余情况转交给主模块图，这也是为什么 claude --version 能几乎瞬间返回。

这层最重要的工程思想是：把高频、低复杂度路径从重型依赖树里剥离出去。不是所有命令都值得为了一次简单输出把整套 REPL 和会话系统拉起来。

// cli.tsx — fast-path: --version needs zero imports
const args = process.argv.slice(2)
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`)
  return
}

// For all other paths, load the startup profiler first
const { profileCheckpoint } = await import('../utils/startupProfiler.js')
profileCheckpoint('cli_entry')

装载前 main.tsx, cli.tsx 还可以处理环境突变 must 发生在进程启动时，在任何模块评估之前：COREPACK 固定被禁用，并且 CCR 容器通过以下方式获得 8 GB 堆上限 NODE_OPTIONS.

第 2 阶段 — 并行预取副作用（main.tsx top-level)

main.tsx 文件顶部那些副作用调用，核心价值并不是“早一点开始”，而是“与模块加载并行”。在主模块树还在求值时，MDM 读取和钥匙串预取已经在后台跑了。

这类并行化对启动体验的影响很大，因为首屏延迟往往不是某一个调用慢，而是一串调用排队串行。把 I/O 和模块求值重叠起来，本质上是在缩短关键路径。

// These side-effects must run before all other imports:
profileCheckpoint('main_tsx_entry')   // timestamp: module eval started

startMdmRawRead()     // fires plutil/reg query subprocesses in parallel
startKeychainPrefetch() // starts macOS keychain reads (OAuth + API key)

当大约 135 毫秒的静态导入完成加载时，MDM 策略和钥匙串读取已经开始运行。 这种并行性大大缩短了首次验证流程的时间。

第 3 阶段 — Commander 参数解析

模块加载完成后，Claude Code 才真正进入参数解析阶段。这里不只是把 flag 读出来，而是在决定会话如何启动：工作目录是什么、权限模式是什么、是否恢复旧会话、要不要连接 MCP、是否走 print / bare 路径。

也正因为这里是启动分叉点，迁移、设置预热和 Commander 解析会被紧密排在一起。只要这一步定下来，后续 setup 就能按一个明确的运行模式来组装整条链路。

// main.tsx — runs migrations once per config version bump
const CURRENT_MIGRATION_VERSION = 11
function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings()
    migrateSonnet45ToSonnet46()  // example: model string upgrades
    migrateOpusToOpus1m()
    // ...8 more migration functions...
    saveGlobalConfig(prev => ({ ...prev, migrationVersion: CURRENT_MIGRATION_VERSION }))
  }
}

第四阶段—— setup() in setup.ts

setup() 是启动链里真正“把会话接上线”的地方。它不只是做环境检查，而是在确定 cwd、启动 UDS、捕获 Hook 配置、初始化会话记忆、预取命令和插件，并最终把系统推进到可渲染状态。

这一步顺序要求极强。比如先 setCwd() 再抓 Hook，先附加 sinks 再打 tengu_started，都不是风格问题，而是为了保证安全性、统计口径和会话一致性。

1. Node.js 版本门（需要≥18）
2. 可选的自定义会话 ID 通过 switchSession()
3. UDS (Unix Domain Socket) 消息传递服务器启动 — 因此挂钩进程可以找到套接字
4. 队友/群体快照（仅限非裸模式）
5. iTerm2 和 Terminal.app 备份恢复中断的设置
6. setCwd(cwd) — 必须发生在读取 cwd 的任何内容之前
7. Hooks 配置快照 — 读取 .claude/settings.json 来自新的cwd
8. FileChanged 钩子观察器初始化
9. 可选的工作树创建 + tmux 会话
10. 后台工作： initSessionMemory(), getCommands(), 插件挂钩
11. initSinks() — 附加分析+错误接收器，排出排队事件
12. logEvent('tengu_started') — 第一个可靠的“进程启动”信标
13. API 密钥预取（仅限安全路径）
14. 发行说明检查+最近活动获取
15. 权限安全检查（root/sudo Guard、Docker 沙箱门）
16. 记录的上一个会话退出指标 projectConfig

// setup.ts — setCwd ordering comment (verbatim from source)
// IMPORTANT: setCwd() must be called before any other code that depends on the cwd
setCwd(cwd)

// IMPORTANT: Must be called AFTER setCwd() so hooks are loaded from the correct directory
captureHooksConfigSnapshot()

阶段 5 — 全局状态 (bootstrap/state.ts)

state.ts 是所有会话范围内的全局状态的单一事实来源。 楼上的评论说的很清楚了： “不要在这里添加更多状态——对全局状态要谨慎。”

跟踪的状态包括：

// bootstrap/state.ts — initial state factory (simplified excerpt)
function getInitialState(): State {
  let resolvedCwd = ''
  try {
    // Resolve symlinks so session storage paths are consistent
    resolvedCwd = realpathSync(cwd())
  } catch { resolvedCwd = cwd() }

  return {
    originalCwd: resolvedCwd,
    projectRoot: resolvedCwd,
    sessionId: asSessionId(randomUUID()),
    isInteractive: true,
    totalCostUSD: 0,
    // ... ~60 more fields
  }
}

阶段 6 — 墨水渲染 (replLauncher.tsx + ink.ts)

最后一步是渲染基于 React 的 TUI。 launchRepl() 动态导入 App and REPL 组件（避免循环导入）然后调用 renderAndRun():

// replLauncher.tsx
export async function launchRepl(
  root: Root,
  appProps: AppWrapperProps,
  replProps: REPLProps,
  renderAndRun: (root: Root, element: React.ReactNode) => Promise<void>,
): Promise<void> {
  const { App }  = await import('./components/App.js')
  const { REPL } = await import('./screens/REPL.js')
  await renderAndRun(root, <App {...appProps}><REPL {...replProps} /></App>)
}

ink.ts 包装每个渲染调用 <ThemeProvider> 自动地，所以 ThemedBox and ThemedText 组件无需每个调用站点都安装主题上下文即可工作：

// ink.ts — wraps every render with ThemeProvider
function withTheme(node: ReactNode): ReactNode {
  return createElement(ThemeProvider, null, node)
}

export async function render(node, options) {
  return inkRender(withTheme(node), options)
}