13 · 构建与分发

最后一章讲：51 万行 TypeScript 是怎么变成一个能双击运行的文件的，以及这个构建过程本身如何反过来塑造了代码的写法。

13.1 Bun 单文件可执行程序

先看事实：

$ ls -la ~/.local/share/claude/versions/
-rwxr-xr-x  272553824  2.1.223      ← 260 MB
-rwxr-xr-x  279661952  2.1.226      ← 267 MB
-rwxr-xr-x  310740672  2.1.234      ← 296 MB

一个文件，296 MB，直接可执行。不需要装 Node.js，不需要 npm install，不需要任何运行时依赖。

这是 Bun 的一个能力：它可以把「JavaScript 运行时 + 你的全部代码 + 全部依赖包 + 所有静态资源」打包进一个二进制文件。

内嵌原生程序

第 4.4 节提到过一个条件判断：

// Ant-native builds have bfs/ugrep embedded in the bun binary (same ARGV0
// trick as ripgrep). When available, find/grep in Claude's shell are aliased
// to these fast tools, so the dedicated Glob/Grep tools are unnecessary.
...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

译：内部原生构建版把 bfs / ugrep 内嵌进了 bun 可执行文件（用的是和 ripgrep 一样的 ARGV0 技巧）。当它们可用时，Claude 的 shell 里的 find/grep 被别名指向这些快速工具，所以独立的 Glob/Grep 工具就不必要了。

13.2 编译期特性开关：89 个

源码里到处是这样的写法：

import { feature } from 'bun:bundle'

const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js') as typeof import('...'))
  : null

if (feature('CONTEXT_COLLAPSE')) {
  collapseOwnsIt = (contextCollapse?.isContextCollapseEnabled() ?? false) && isAutoCompactEnabled()
}

统计下来共有 89 个不同的编译期开关。部分列表：

13.3 死代码消除：为什么这不只是「if 判断」

feature() 和普通的运行时判断有本质区别：它在打包时被替换成字面量 true 或 false，然后打包器会把不可达的分支整段删除。

这带来三个后果：

「排除字符串」检查催生的编码风格

源码里有多处这样的注释：

// Entire block gated behind feature() so the excluded string
// is eliminated from external builds.
if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) { ... }

// The subtype check lives inside the injected callback so feature-gated
// strings stay out of this file (excluded-strings check).
snipReplay?: (yieldedSystemMsg, store) => { messages, executed } | undefined

第二段尤其能说明问题。为了让某个内部功能的字符串不出现在外部产物里，他们把一段逻辑改成了「由外部注入的回调函数」 —— 这样那个字符串就只存在于注入方（内部构建才编译的模块）里。

另一处：ESLint 规则也参与了

// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
/* eslint-disable custom-rules/no-top-level-side-effects */

可以看到多条自定义的 lint 规则：

• custom-rules/no-process-env-top-level —— 禁止在模块顶层读环境变量（因为顶层代码在导入时就执行，会破坏快路径的「零加载」）
• custom-rules/no-top-level-side-effects —— 禁止顶层副作用（同上）
• custom-rules/require-tool-match-name —— 要求用统一的工具名匹配函数（因为工具有别名，直接比较字符串会漏）
• 「ANT-ONLY 导入标记不能被重排序」—— 自动整理导入的工具会打乱那些标记，导致死代码消除失效

这些规则是构建约束的自动化守卫。不是靠代码评审时人肉检查，而是让违规的代码直接过不了检查。

13.4 编译期宏

// MACRO.VERSION is inlined at build time
console.log(`${MACRO.VERSION} (Claude Code)`)

MACRO 是构建时被替换成字面量的宏。所以 --version 这条快路径连读一个配置文件都不需要（第 1.2 节）。

13.5 运行时特性开关：另一套系统

除了编译期开关，还有一套运行时开关，用的是 GrowthBook（一个 A/B 实验平台）：

const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)

注意这个函数名：getFeatureValue_CACHED_MAY_BE_STALE（获取特性值_已缓存_可能是过期的）。

两套开关的分工

两者经常叠加使用：编译期开关决定「这段代码在不在」，运行时开关决定「在的话要不要执行」。第 6.3 节的缓存微压缩就是这样：

if (feature('CACHED_MICROCOMPACT')) {              // 编译期：外部版本没有这段代码
  const mod = await getCachedMCModule()
  if (mod.isCachedMicrocompactEnabled() &&         // 运行时：可以随时关掉
      mod.isModelSupportedForCacheEditing(model) &&
      isMainThreadSource(querySource)) {
    return await cachedMicrocompactPath(messages, querySource)
  }
}

13.6 版本与更新

安装目录的结构说明了更新策略：

~/.local/share/claude/
├── ClaudeCode.app/                桌面应用
└── versions/
    ├── 2.1.223                    ← 旧版本保留
    ├── 2.1.226                    ← 旧版本保留
    └── 2.1.234                    ← 当前版本

~/.local/bin/claude  →  符号链接指向 versions/2.1.234

多个版本并存，通过符号链接切换当前版本。这样：

• 更新是「下载新版本 + 改符号链接」，原子操作，不会出现「更新到一半程序坏了」
• 出问题可以秒回滚（改回符号链接）
• 正在运行的旧版本进程不受影响（它已经把文件加载进内存了）

代价是磁盘占用 —— 三个版本就是 800 MB。所以 utils/nativeInstaller/installer.ts（53 KB）里应该有清理旧版本的逻辑。

13.7 从构建方式反推的架构约束

这一章的内容其实在前面每一章都留下了痕迹。汇总一下「构建方式如何塑造了代码」：