第3章 CLI 启动与性能优化

"The cheapest, fastest, and most reliable components are those that aren't there." -- Gordon Bell

本章要点

三阶段启动模型 -- Claude Code 将启动过程拆分为副作用阶段、导入阶段和 CLI 分发阶段，每个阶段都有针对性的优化策略
并行预加载模式 -- 利用 JavaScript 模块求值的同步特性，在 import 语句执行期间并行运行子进程，实现"零成本"预加载
编译期特性标志 -- 通过 Bun bundler 的 feature() 机制实现死代码消除，使外部构建产物不包含内部功能的任何字节
快速路径设计 -- 对 --version、--dump-system-prompt、daemon worker 等场景设计零依赖或最小依赖的快速退出路径
端到端性能度量 -- 基于 profileCheckpoint 的全链路性能分析体系，支持采样上报和详细本地报告两种模式

引言：毫秒之战

一个 CLI 工具的启动时间，直接决定了用户的第一印象。当开发者在终端输入 claude 并按下回车，到看到交互式提示符，中间经历的每一毫秒都在消耗用户的耐心。对于 Claude Code 这样一个需要加载大量模块、读取多处配置、建立网络连接的复杂工程来说，启动性能优化是一场精密的毫秒之战。

Claude Code 的启动优化并非事后补救，而是从架构层面就融入了设计。它的核心思想可以概括为：让一切可以并行的操作并行执行，让一切不必要的代码不出现在产物中，让一切可以延迟的初始化推迟到真正需要时。

本章将沿着一次完整的 CLI 启动流程，从用户敲下 claude 命令开始，逐步剖析每个阶段的设计决策和优化手段。

3.1 启动的三个阶段

Claude Code 的启动过程被精心划分为三个阶段，每个阶段有不同的目标和约束。理解这三个阶段，是理解后续所有优化策略的基础。

以下流程图展示了 CLI 启动的三阶段模型及其内部并行关系：

3.1.1 入口分层架构

在深入三个阶段之前，有必要先了解 Claude Code 的入口分层架构。CLI 的执行并不是从一个单一的巨型文件开始的，而是经过两层分发：

cli.tsx (薄入口层)
  |-- 快速路径: --version, --dump-system-prompt, --daemon-worker, bridge, daemon ...
  |-- 主路径: 加载 main.tsx
        |-- 副作用阶段 (Side-Effect Phase)
        |-- 导入阶段 (Import Phase)
        |-- CLI 分发阶段 (CLI Dispatch Phase)

cli.tsx 是最外层的入口（位于 src/entrypoints/cli.tsx），它的设计哲学是：尽可能少地加载模块，尽可能快地判断是否可以短路返回。只有当请求确实需要完整的交互式 CLI 时，才会加载体量庞大的 main.tsx。

3.1.2 副作用阶段（Side-Effect Phase）

副作用阶段是 main.tsx 文件的前 20 行，也是整个启动过程中最精妙的部分。我们直接看源码：

typescript

// 文件: src/main.tsx (第1-20行)

// 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 — isRemoteManagedSettingsEligible() otherwise reads them
//    sequentially via sync spawn inside applySafeConfigEnvironmentVariables()
//    (~65ms on every macOS startup)
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';

// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint('main_tsx_entry');
import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';

// eslint-disable-next-line custom-rules/no-top-level-side-effects
startMdmRawRead();
import { ensureKeychainPrefetchCompleted, startKeychainPrefetch }
  from './utils/secureStorage/keychainPrefetch.js';

// eslint-disable-next-line custom-rules/no-top-level-side-effects
startKeychainPrefetch();

这段代码的结构乍看古怪 -- 为什么函数调用和 import 语句交替出现？这正是它的精髓所在。

在 JavaScript 中，import 语句是同步的、顺序求值的。当运行时遇到 import { startMdmRawRead } from './utils/settings/mdm/rawRead.js' 时，它会立即加载并执行 rawRead.js 模块的全部代码，然后才继续执行下一行。利用这个特性，Claude Code 在每个 import 之后立即调用刚导入的函数，让异步子进程在后台启动，然后继续加载下一批模块。

这三个操作按精确的顺序排列：

profileCheckpoint('main_tsx_entry') -- 记录一个时间戳锚点，后续所有计时都以此为参照
startMdmRawRead() -- 立即启动 MDM（Mobile Device Management）配置读取子进程
startKeychainPrefetch() -- 立即启动 macOS Keychain 读取子进程

之所以它们必须在"所有其他 import 之前"执行（代码注释中的 "must run before all other imports"），是因为后续的 import 语句链（第 22-206 行）将触发大量模块求值，耗时约 135ms。这 135ms 就是一个天然的"空闲窗口" -- 子进程可以在这个窗口中完成它们的 I/O 操作，实现真正的零成本预加载。

3.1.3 导入阶段（Import Phase）

副作用阶段结束后，紧接着是一长串的 import 语句，从第 21 行一直延伸到第 206 行：

typescript

// 文件: src/main.tsx (第21-209行，节选)

import { feature } from 'bun:bundle';
import { Command as CommanderCommand, InvalidArgumentError, Option }
  from '@commander-js/extra-typings';
import chalk from 'chalk';
import { readFileSync } from 'fs';
import mapValues from 'lodash-es/mapValues.js';
// ... (约185行 import 语句)
import { shouldEnableThinkingByDefault, type ThinkingConfig }
  from './utils/thinking.js';
import { initUser, resetUserCache } from './utils/user.js';

// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint('main_tsx_imports_loaded');

注意最后一行 profileCheckpoint('main_tsx_imports_loaded') -- 这标记了导入阶段的结束。结合前面的 main_tsx_entry 检查点，我们就能精确测量出所有 import 语句的总耗时。

在启动性能分析器（startupProfiler.ts）中，这个阶段被定义为：

typescript

// 文件: src/utils/startupProfiler.ts (第49-54行)

const PHASE_DEFINITIONS = {
  import_time: ['cli_entry', 'main_tsx_imports_loaded'],
  init_time: ['init_function_start', 'init_function_end'],
  settings_time: ['eagerLoadSettings_start', 'eagerLoadSettings_end'],
  total_time: ['cli_entry', 'main_after_run'],
} as const;

这些 import 语句加载了 Claude Code 运行所需的核心基础设施：Commander.js 命令行框架、React/Ink 终端 UI 框架、各种工具模块、权限系统、分析服务等。每条 import 都触发对应模块文件的同步求值，包括该模块自身的所有 import 依赖 -- 这就是为什么总耗时会达到约 135ms。

在导入阶段，代码还利用了 feature() 函数做条件加载（详见 3.3 节）：

typescript

// 文件: src/main.tsx (第74-81行)

// Dead code elimination: conditional import for COORDINATOR_MODE
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js') : null;

// Dead code elimination: conditional import for KAIROS (assistant mode)
const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js') : null;
const kairosGate = feature('KAIROS')
  ? require('./assistant/gate.js') : null;

第3章 CLI 启动与性能优化 ​

引言：毫秒之战 ​

3.1 启动的三个阶段 ​

3.1.1 入口分层架构 ​

3.1.2 副作用阶段（Side-Effect Phase） ​

3.1.3 导入阶段（Import Phase） ​

第3章 CLI 启动与性能优化

引言：毫秒之战

3.1 启动的三个阶段

3.1.1 入口分层架构

3.1.2 副作用阶段（Side-Effect Phase）

3.1.3 导入阶段（Import Phase）