简介Claude Code官方源码的完整还原包基于source-map逆向整理面向AI架构师、智能体研发与上下文工程研究者。资源聚焦企业级Agent推理框架、思维链控制、长上下文优化与多模态任务处理可用于分析Claude Code从上下文理解到工具调用的全链路实现。包内共534个文件约15.9MB以TypeScript源码199个ts、source-map映射文件117个map、React组件100个tsx及可执行模块50个mjs/49个js为主辅以Markdown文档、配置文件与Wasm运行时目录结构与原始工程高度对应便于按模块深入研读。目前已有5850人学习。借助还原后的源码可系统拆解上下文记忆管理、状态维护、任务分解与生产级API设计等核心机制同时获得可定制的扩展接口参考对自研Agent框架或优化长上下文方案极具参考价值。1. 拿到 claude-code 官方包别急着跑命令源码其实藏在 .map 里Claude Code 以压缩后的 JS 分发给所有用户真正的人类可读源码不在发行包里。但打开安装目录往里看会发现同名的 .map 文件体积比主文件还大——这就是 source-map。构建工具把原始 TypeScript 源码内容直接塞进了这个 JSON也就是说官方源码并没有消失只是换了一种姿势躺在发行包里等着被还原。这篇文章讲的就是如何基于 source-map 把 claude-code 的官方源码还原出来从 map 文件结构讲到最小还原脚本、路径清洗、大文件避坑最后用运行时堆栈反向验证还原结果是否可信。适合三类人想搞清楚这个 AI 编程工具内部机制的人、要基于官方源码做二次开发的人、以及只看过压缩代码但对 source-map 还原流程不熟的开发者。读完你就能自己动手拿到任何带 map 的 npm 包十分钟把源码落盘。2. claude-code 的 source-map 结构sourcesContent 才是还原的命门2.1 官方发行包为什么敢把 .map 一起发出来发行包通常会把代码压缩混淆变量名变短、换行消失、模块被内联目的之一是减小体积另一个原因是源码属于核心资产。但压缩后的代码一旦在生产环境出问题报错堆栈几乎没法定位——你只知道 cli.js 第 32458 行崩了而这一行是几百个字符挤在一起的一坨根本看不出是哪个函数。source-map 就是为这个场景诞生的构建打包时记录每一段压缩代码与原始代码的对应关系运行时错误通过它映射回原始行列。所以主流打包工具在发版时都会带上 .map不然线上报错等于黑匣子。Claude Code 这类用 Node 发行的 CLI 工具也一样官方发行包里附带 .map 文件是给自己和插件生态排查问题用的不是专门留给逆向的。不过正因为这个排错用途.map 里塞的信息量远超预期。常见的打包器webpack、esbuild 这类在生成 source map 时会把原始文件内容直接内嵌进 map字段叫sourcesContent。它是构建那一刻 src 目录下文件内容的完整快照连注释都原样保留。这意味着 source-map 还原这件事绝大多数时候不需要你去破解压缩逻辑只需要把sourcesContent这个数组按路径写回磁盘。理解到这一层后面所有操作都顺了还原 读取 → 配对路径 → 落盘核心难点反而变成路径怎么清洗、大文件内存怎么控、以及还原产物和真实执行代码之间的差异怎么看待。2.2 拆开一个 .mapsources、sourcesContent、mappings 各自管什么一个标准的 source-map JSON 长这样字段不多但每个都对应一种还原手段{ version: 3, file: cli.js, sources: [ webpack://claude-code/./src/loader.ts, webpack://claude-code/./src/session.ts ], sourcesContent: [ import { ... } from ...;, export function ... { ... } ], names: [sessionId, readFile], mappings: AAAA,CAACA,CAAC }sources是原始文件的路径列表记录成模块路径通常带webpack://或file://前缀sourcesContent是和sources一一对应的原始文件内容数组两者长度必须一致这是还原的最关键字段mappings是一串 VLQ 编码的映射文本记录压缩后每个位置的列对应原始文件的哪一行哪一列它是做运行时堆栈映射用的还原整个文件时几乎用不上names是标识符名列表配合mappings里的符号索引找回原始变量名。提示还原代码和解析 mappings 是两件事。只要sourcesContent在直接按数组下标把内容写进对应路径就完成了完全不用碰那串像天书一样的 VLQ 文本。反过来如果sourcesContent缺失只能靠 mappings 逐行拆回原始结构工作量巨大且结果残缺基本等于不可行。所以拿到 map 的第一步不是写解析器而是先确认sourcesContent在不在、完整不完整。2.3 还原的三条路直读数组、源码映射库、DevTools 代劳针对不同的目的还原有三条常见路径我一般会按场景选。第一条是直读sourcesContent数组脚本最短、速度最快、不引入任何第三方依赖适合一次性还原整个包缺点是要自己处理字段缺失和路径清洗第二条是用官方source-map库走完整解析可以同时拿到sourcesContent和解析后的映射对象方便后面做堆栈反查、单行定位这类交互操作代价是内存占用高对超大 map 不友好第三条是用浏览器 DevTools 的 Sources 面板直接打开 cli.jsDevTools 会自动读取同目录下的 .map 文件并把源码展示在 Sources 树里零脚本适合快速翻阅但不方便落盘成项目目录也没法批量导出。三条路的取舍可以这样看还原路径依赖适合场景主要代价直读 sourcesContent 数组无批量落盘、还原整个源码工程需自己清洗路径、处理空条目source-map 库完整解析source-map npm 包单点堆栈反查、交互式定位内存占用大、解析慢DevTools Sources 面板浏览器快速阅读源码不方便导出不能批量这三条路对应不同诉求只想读代码用第三条想拿到可检索的源码工程用第一条想深入调试原始逻辑用第二条。后面章节我按先直读落盘、再用库做验证的顺序展开这也是实际项目里最高效的组合。3. 动手前先摸清 claude-code 的包目录定位安装位置与全部 .map 文件3.1 找到真实安装位置用命令而不是靠记忆还原的第一步不是写脚本是先找到包里那些 .map 文件在哪。claude-code 作为命令行工具装完之后主程序和辅助文件会在几个固定位置之一通过包管理器全局安装时在全局 node_modules 目录下通过官方安装脚本安装时通常在用户主目录的隐藏目录里。不同系统、不同安装方式位置都不一样别靠记忆去猜直接让系统告诉你。# 找到 claude-code 的主命令路径 which claude-code # 如果主命令是符号链接再解析出真实文件位置 readlink -f $(which claude-code)第一个命令拿到的是命令入口在 Unix 系系统里它通常是一个软链指向实际包目录里的 cli.js第二个命令把软链层层解析到真实路径。拿到真实路径后包根目录就在cli.js同级的目录里.map 文件和它放在一起。用这种方式定位最稳因为手动去翻用户主目录很容易被版本目录、缓存目录干扰找半天也未必定位到真正被执行的那一份。注意 Windows 环境下没有readlink -f可以用where claude-code加Get-Item的LinkType判断思路一致先找入口再解析真实路径。3.2 一条命令摸清所有 .map 文件与对应的压缩产物确定包根目录后把整个目录下的 .map 文件清单拉出来顺便看下每个文件大小。这一步能让你对还原工作量和策略心里有数如果主文件旁边只有一个体积数倍于主文件的 .map说明这是单文件大 bundle直读sourcesContent就行如果散落着十几个 .map说明是分包产物需要批量处理并且每份 map 对应的压缩文件不同还原时要分别对齐。# 假设包根目录是 ~/.local/share/claude-code按实际路径替换 find ~/.local/share/claude-code -name *.map -printf %p\t%s bytes\n | sort # 查看主文件末尾的 sourceMappingURL 注释确认它引用的是哪个 map tail -c 500 ~/.local/share/claude-code/cli.js | grep -o sourceMappingURL[^ ]*find 输出每个 map 的完整路径和字节数按路径排序后能看到完整的 map 分布。tail 那步是从压缩产物末尾抓//# sourceMappingURLcli.js.map这类注释它是浏览器和调试器定位 map 的依据也可以反向确认哪个 map 对应哪个压缩文件。如果包里存在 map 文件但主文件末尾没有这行注释说明 map 是单独分发或已被剥离调试器不会自动加载但脚本还原不受影响因为还原脚本读的是 map 本身不依赖这个注释。3.3 预检 sourcesContent决定还原策略的关键一步这一步是决定成败的预检别跳过。map 文件通常很大先把整个 JSON 读进来才发现字段缺失浪费时间。先用命令行工具做一次轻量检查读 JSON对比sources数组和sourcesContent数组的长度并抽查几个元素是否是非空字符串。# 用 node 做快速体检不解析 mappings只读字段信息 node -e const fs require(fs); const map JSON.parse(fs.readFileSync(process.argv[1], utf8)); const sc map.sourcesContent; console.log(sources:, map.sources.length); console.log(sourcesContent:, sc ? sc.length : undefined); if (sc) { const empty sc.filter(v !v).length; console.log(empty entries:, empty); console.log(sample:, sc.find(Boolean)?.slice(0, 80)); } /path/to/cli.js.map这个脚本把两个关键数组的长度打出来并统计空条目。正常情况下sources和sourcesContent长度一致、空条目为零、sample 里能看到import、export这类 TypeScript 源码开头。如果打印出来的是undefined或者空条目占了大半后面就不能依赖直读方案得考虑换一个带完整sourcesContent的版本或者接受只能做堆栈映射、还原不出全量源码的现实。这一步值得花两分钟因为它直接决定整个方案走哪条路也能避免后续脚本白跑一趟。4. 还原落盘最小直读脚本、source-map 库写法与产物校验4.1 不解析 mappings 的直读脚本最短路径把源码写回磁盘确认sourcesContent完整后还原本身出乎意料地简单。不需要引入任何第三方库读 JSON、按下标配对路径和内容、写文件三步走完。我把脚本写成一个通用工具传入一个或多个 map 文件路径即可同时内置了路径清洗和越界保护。// restore-sourcemap.js —— 直读 sourcesContent 批量还原源码 const fs require(fs); const path require(path); const OUT_ROOT path.resolve(process.env.OUT_DIR || restored); const files process.argv.slice(2); for (const mapFile of files) { const map JSON.parse(fs.readFileSync(mapFile, utf8)); const { sources, sourcesContent } map; if (!Array.isArray(sourcesContent)) { console.error([skip] ${mapFile}: no sourcesContent); continue; } sources.forEach((src, i) { const content sourcesContent[i]; if (typeof content ! string) return; // 空条目跳过 const outPath safeResolve(src, OUT_ROOT); if (!outPath) return; fs.mkdirSync(path.dirname(outPath), { recursive: true }); fs.writeFileSync(outPath, content, utf8); }); console.log([done] ${mapFile} - ${OUT_ROOT}); } // 把 sources 里的路径清洗后收敛到 OUT_ROOT 下防止路径逃逸 function safeResolve(src, root) { let p src .replace(/^webpack:\/\/[^/]*\//, ) // 去掉协议头和包名 .replace(/^file:\/\//, ) // 去掉 file:// 前缀 .replace(/^\.\//, ); // 去掉开头的 ./ const abs path.resolve(root, p); if (!abs.startsWith(root path.sep) abs ! root) { console.warn([warn] path escapes root: ${src}); return null; } return abs; }逻辑说明脚本核心是sources.forEach那段——sources和sourcesContent是等长数组下标一致直接把第 i 个内容写到第 i 个路径上。safeResolve负责路径清洗压缩包里 sources 往往带着webpack://claude-code/./src/xxx.ts这种前缀第一步把协议头和包名剥掉剩下的./src/xxx.ts再落盘到输出根目录最后用startsWith(root)判断是否逃逸防止 sources 里出现../../把文件写到还原目录之外。参数说明OUT_DIR环境变量控制输出目录默认restored命令行传入多个 map 文件时脚本逐个处理每个 map 的输出都收敛在同一根目录下。这个直读方案的快就在于跳过了整个 mappings 解析。对一个几十 MB 的 mapJSON.parse本身是主要耗时解析 VLQ 映射反而更慢更吃内存。4.2 需要堆栈反查时再上 source-map 库originalPositionFor 的用法直读方案适合批量落盘但如果你后续要做压缩代码行号 → 原始代码行号的映射就需要真正解析 mappings。标准做法是用source-map这个 npm 库它把 VLQ 解码、索引构建都封装好了。// map-stack.js —— 用 source-map 解析 map演示单点映射 const { SourceMapConsumer } require(source-map); const fs require(fs); const mapData JSON.parse(fs.readFileSync(process.argv[2], utf8)); SourceMapConsumer.with(mapData, null, (consumer) { // 示例把压缩产物第 100 行第 5 列映射回原始位置 const pos consumer.originalPositionFor({ line: 100, column: 5 }); console.log(original:, pos); // 也可以像直读方案一样导出全部 sourcesContent consumer.sources.forEach((src, i) { if (consumer.sourcesContent[i]) { // 写盘逻辑复用 4.1 的 safeResolve此处省略 } }); }).catch((err) console.error(parse failed:, err.message));逻辑说明SourceMapConsumer.with是库推荐的入口传入 map 的 JSON 对象回调里拿到 consumer 实例。originalPositionFor接收压缩产物的行列号返回{ source, line, column, name }这样的结构这就是运行时堆栈反查的基础。参数说明line和column均从 1 开始计数部分工具返回 0 基结果对齐时注意换算回调里同样可以读取consumer.sourcesContent做导出和直读脚本的差异是这里额外解析了 mappings内存开销约为 map 本身的两到三倍。如果只是还原源码没必要走这条路如果要做后续调试这条路能省去自己解析 VLQ 的工夫代价是 Node 堆要留足。4.3 校验还原产物文件数、入口、关键符号三连查落盘之后别急着收工先校验一次还原产物是否可信。校验分三层第一层看文件数量和路径结构是否符合预期第二层看是否有入口文件能对应上 cli.js 的启动逻辑第三层抽查几个关键符号确认代码不是占位符。我用一条命令完成前两层。# 统计还原出的文件数与非空文件数 find restored -type f | wc -l find restored -type f -size 0c | wc -l # 查找入口类文件通常是 cli.ts / main.ts / command 相关文件 find restored -name cli.ts -o -name main.ts | head -20文件总数和非空文件数如果相差很大说明有一部分 sources 对应的sourcesContent是空的要返回去检查预检步骤里的 empty entries。入口文件的存在与否是更强的信号claude-code 这种 CLI 工具的源码必然有一个启动入口找到它之后打开看如果看到参数解析、命令分发、主流程调用这些内容还原基本就成功了。最后再抽查一个模块文件找一个你熟悉的函数名在还原产物里追踪它的调用链确认代码是完整的、可读的。这三层都过了还原产物才能作为后续分析的基础否则就要回到第 3 章的预检重新排查。5. 还原避坑记录五个真实翻车现场与排查方法5.1 现象sources 有值sourcesContent 全为空还原出来一堆空文件原因不是所有发行版的 map 都带sourcesContent。部分构建配置会开hidden-source-map或为了省体积把内容剥离只保留定位映射。空文件比字段缺失更难提前发现因为数组长度对得上脚本不会报错。解决还原前先跑 3.3 的预检脚本重点关注 empty entries 数量如果为空放弃直读方案要么换一个带完整sourcesContent的版本要么接受只做堆栈映射、不做全量还原的降级方案。不要试图从 mappings 里反推源码那是把几个月的工时砸进无底洞。5.2 现象还原出的文件路径乱飞出现 restored/../../ 越权目录甚至写到还原目录之外原因sources 里的路径不是为落盘设计的。它可能是webpack://包名/./src/a.ts也可能是../node_modules/...这种相对路径直接path.resolve(mapFilePath, src)时..会被解析成目录上跳。解决所有路径先做协议头剥离和../收敛再用startsWith(root)做越界判断越界的文件直接丢弃并在日志里警告。我用 4.1 里safeResolve就是这个目的实际项目里我还加过一层把node_modules前缀的路径统一重写到vendor/目录下保持还原目录整洁方便区分第三方依赖和本体代码。5.3 现象Node 进程解析 map 时内存暴涨直接 OOM小机器上第一次跑就崩原因JSON.parse要一次性把整个 map 读进内存SourceMapConsumer又要构建一份映射索引两个大对象叠加几百 MB 的 map 能吃掉 2GB 以上的堆。解决纯还原场景不用SourceMapConsumer用原始 JSON 直读只访问sources和sourcesContent两个字符串数组如果必须用库启动时给 Node 显式加大堆node --max-old-space-size4096 map-stack.js cli.js.map。另外优先单独处理大 map而不是一次性把所有 map 文件传给同一个进程失败时也更好定位是哪一个文件的问题。5.4 现象还原出来的是 TypeScript对照着看逻辑总觉得和实际行为对不上原因map 记录的是构建时的原始源码而运行的是经过转译、内联、摇树之后的 JS。TypeScript 的枚举、装饰器、泛型在转译后形态完全不同被摇树删掉的模块源码里还在但运行时根本不存在。解决把还原产物当成阅读用参考实现排查问题时仍然以运行时行为和实际堆栈为准。想看某个函数到底怎么执行不要只盯着还原的 TS 看用第 6 章的反查手法把运行时行号映射回来两者对照才可靠。5.5 现象map 与发布产物不一致堆栈反查落到了错误位置原因source map 对应的可能是构建缓存或发布流水线里某一跳的产物和最终发布出去的 cli.js 不是完全同一份代码。发布环节偶尔会出现 map 更新滞后导致 mappings 对不上实际产物。解决拿到 map 后先做配套性检查直接拿 cli.js 里某一段特征字符串去源码里 grep对得上再深入分析对不上的 map 宁可不用也别硬着头皮往下走否则所有结论都建在错误的地基上排查问题会越排越偏。6. 进阶验证把运行时堆栈映射回还原源码确认整套还原可信还原完源码最有说服力的验证不是文件能打开而是把运行时报错的行号映射回还原后的源码看能不能精准落到具体的函数和参数上。做法很简单让 claude-code 在某个场景下抛一个错误拿到压缩代码里的行号列号然后调用SourceMapConsumer的originalPositionFor把还原后的源码文件和行列打印出来。如果还原产物里能定位到那个函数说明 map 和产物是配套的整个还原链路可信。// verify-map.js —— 传入 cli.js 的报错行列反查原始位置 const { SourceMapConsumer } require(source-map); const fs require(fs); const mapData JSON.parse(fs.readFileSync(cli.js.map, utf8)); SourceMapConsumer.with(mapData, null, (consumer) { const pos consumer.originalPositionFor({ line: Number(process.argv[2]), column: Number(process.argv[3]) }); console.log(pos.source, ${pos.line}:${pos.column}, pos.name || ); });跑一次之后再去还原产物里打开那个文件定位到对应行如果上下文和报错信息对得上这个项目就值得你投入研究。我现在的习惯是凡是拿到带 map 的工具包先还原、再抽查三处运行时堆栈、最后把还原结果单独备份一份免得包升级后文件被覆盖。往后你分析任何闭源打包的 Node 工具这条 source-map 还原路径都能复用省下的摸索时间很可观。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/18 16:06:53 · 阅读 1.2k 借助source-map还原Claude Code官方源码：原理、脚本与避坑指南
简介Claude Code官方源码的完整还原包基于source-map逆向整理面向AI架构师、智能体研发与上下文工程研究者。资源聚焦企业级Agent推理框架、思维链控制、长上下文优化与多模态任务处理可用于分析Claude Code从上下文理解到工具调用的全链路实现。包内共534个文件约15.9MB以TypeScript源码199个ts、source-map映射文件117个map、React组件100个tsx及可执行模块50个mjs/49个js为主辅以Markdown文档、配置文件与Wasm运行时目录结构与原始工程高度对应便于按模块深入研读。目前已有5850人学习。借助还原后的源码可系统拆解上下文记忆管理、状态维护、任务分解与生产级API设计等核心机制同时获得可定制的扩展接口参考对自研Agent框架或优化长上下文方案极具参考价值。1. 拿到 claude-code 官方包别急着跑命令源码其实藏在 .map 里Claude Code 以压缩后的 JS 分发给所有用户真正的人类可读源码不在发行包里。但打开安装目录往里看会发现同名的 .map 文件体积比主文件还大——这就是 source-map。构建工具把原始 TypeScript 源码内容直接塞进了这个 JSON也就是说官方源码并没有消失只是换了一种姿势躺在发行包里等着被还原。这篇文章讲的就是如何基于 source-map 把 claude-code 的官方源码还原出来从 map 文件结构讲到最小还原脚本、路径清洗、大文件避坑最后用运行时堆栈反向验证还原结果是否可信。适合三类人想搞清楚这个 AI 编程工具内部机制的人、要基于官方源码做二次开发的人、以及只看过压缩代码但对 source-map 还原流程不熟的开发者。读完你就能自己动手拿到任何带 map 的 npm 包十分钟把源码落盘。2. claude-code 的 source-map 结构sourcesContent 才是还原的命门2.1 官方发行包为什么敢把 .map 一起发出来发行包通常会把代码压缩混淆变量名变短、换行消失、模块被内联目的之一是减小体积另一个原因是源码属于核心资产。但压缩后的代码一旦在生产环境出问题报错堆栈几乎没法定位——你只知道 cli.js 第 32458 行崩了而这一行是几百个字符挤在一起的一坨根本看不出是哪个函数。source-map 就是为这个场景诞生的构建打包时记录每一段压缩代码与原始代码的对应关系运行时错误通过它映射回原始行列。所以主流打包工具在发版时都会带上 .map不然线上报错等于黑匣子。Claude Code 这类用 Node 发行的 CLI 工具也一样官方发行包里附带 .map 文件是给自己和插件生态排查问题用的不是专门留给逆向的。不过正因为这个排错用途.map 里塞的信息量远超预期。常见的打包器webpack、esbuild 这类在生成 source map 时会把原始文件内容直接内嵌进 map字段叫sourcesContent。它是构建那一刻 src 目录下文件内容的完整快照连注释都原样保留。这意味着 source-map 还原这件事绝大多数时候不需要你去破解压缩逻辑只需要把sourcesContent这个数组按路径写回磁盘。理解到这一层后面所有操作都顺了还原 读取 → 配对路径 → 落盘核心难点反而变成路径怎么清洗、大文件内存怎么控、以及还原产物和真实执行代码之间的差异怎么看待。2.2 拆开一个 .mapsources、sourcesContent、mappings 各自管什么一个标准的 source-map JSON 长这样字段不多但每个都对应一种还原手段{ version: 3, file: cli.js, sources: [ webpack://claude-code/./src/loader.ts, webpack://claude-code/./src/session.ts ], sourcesContent: [ import { ... } from ...;, export function ... { ... } ], names: [sessionId, readFile], mappings: AAAA,CAACA,CAAC }sources是原始文件的路径列表记录成模块路径通常带webpack://或file://前缀sourcesContent是和sources一一对应的原始文件内容数组两者长度必须一致这是还原的最关键字段mappings是一串 VLQ 编码的映射文本记录压缩后每个位置的列对应原始文件的哪一行哪一列它是做运行时堆栈映射用的还原整个文件时几乎用不上names是标识符名列表配合mappings里的符号索引找回原始变量名。提示还原代码和解析 mappings 是两件事。只要sourcesContent在直接按数组下标把内容写进对应路径就完成了完全不用碰那串像天书一样的 VLQ 文本。反过来如果sourcesContent缺失只能靠 mappings 逐行拆回原始结构工作量巨大且结果残缺基本等于不可行。所以拿到 map 的第一步不是写解析器而是先确认sourcesContent在不在、完整不完整。2.3 还原的三条路直读数组、源码映射库、DevTools 代劳针对不同的目的还原有三条常见路径我一般会按场景选。第一条是直读sourcesContent数组脚本最短、速度最快、不引入任何第三方依赖适合一次性还原整个包缺点是要自己处理字段缺失和路径清洗第二条是用官方source-map库走完整解析可以同时拿到sourcesContent和解析后的映射对象方便后面做堆栈反查、单行定位这类交互操作代价是内存占用高对超大 map 不友好第三条是用浏览器 DevTools 的 Sources 面板直接打开 cli.jsDevTools 会自动读取同目录下的 .map 文件并把源码展示在 Sources 树里零脚本适合快速翻阅但不方便落盘成项目目录也没法批量导出。三条路的取舍可以这样看还原路径依赖适合场景主要代价直读 sourcesContent 数组无批量落盘、还原整个源码工程需自己清洗路径、处理空条目source-map 库完整解析source-map npm 包单点堆栈反查、交互式定位内存占用大、解析慢DevTools Sources 面板浏览器快速阅读源码不方便导出不能批量这三条路对应不同诉求只想读代码用第三条想拿到可检索的源码工程用第一条想深入调试原始逻辑用第二条。后面章节我按先直读落盘、再用库做验证的顺序展开这也是实际项目里最高效的组合。3. 动手前先摸清 claude-code 的包目录定位安装位置与全部 .map 文件3.1 找到真实安装位置用命令而不是靠记忆还原的第一步不是写脚本是先找到包里那些 .map 文件在哪。claude-code 作为命令行工具装完之后主程序和辅助文件会在几个固定位置之一通过包管理器全局安装时在全局 node_modules 目录下通过官方安装脚本安装时通常在用户主目录的隐藏目录里。不同系统、不同安装方式位置都不一样别靠记忆去猜直接让系统告诉你。# 找到 claude-code 的主命令路径 which claude-code # 如果主命令是符号链接再解析出真实文件位置 readlink -f $(which claude-code)第一个命令拿到的是命令入口在 Unix 系系统里它通常是一个软链指向实际包目录里的 cli.js第二个命令把软链层层解析到真实路径。拿到真实路径后包根目录就在cli.js同级的目录里.map 文件和它放在一起。用这种方式定位最稳因为手动去翻用户主目录很容易被版本目录、缓存目录干扰找半天也未必定位到真正被执行的那一份。注意 Windows 环境下没有readlink -f可以用where claude-code加Get-Item的LinkType判断思路一致先找入口再解析真实路径。3.2 一条命令摸清所有 .map 文件与对应的压缩产物确定包根目录后把整个目录下的 .map 文件清单拉出来顺便看下每个文件大小。这一步能让你对还原工作量和策略心里有数如果主文件旁边只有一个体积数倍于主文件的 .map说明这是单文件大 bundle直读sourcesContent就行如果散落着十几个 .map说明是分包产物需要批量处理并且每份 map 对应的压缩文件不同还原时要分别对齐。# 假设包根目录是 ~/.local/share/claude-code按实际路径替换 find ~/.local/share/claude-code -name *.map -printf %p\t%s bytes\n | sort # 查看主文件末尾的 sourceMappingURL 注释确认它引用的是哪个 map tail -c 500 ~/.local/share/claude-code/cli.js | grep -o sourceMappingURL[^ ]*find 输出每个 map 的完整路径和字节数按路径排序后能看到完整的 map 分布。tail 那步是从压缩产物末尾抓//# sourceMappingURLcli.js.map这类注释它是浏览器和调试器定位 map 的依据也可以反向确认哪个 map 对应哪个压缩文件。如果包里存在 map 文件但主文件末尾没有这行注释说明 map 是单独分发或已被剥离调试器不会自动加载但脚本还原不受影响因为还原脚本读的是 map 本身不依赖这个注释。3.3 预检 sourcesContent决定还原策略的关键一步这一步是决定成败的预检别跳过。map 文件通常很大先把整个 JSON 读进来才发现字段缺失浪费时间。先用命令行工具做一次轻量检查读 JSON对比sources数组和sourcesContent数组的长度并抽查几个元素是否是非空字符串。# 用 node 做快速体检不解析 mappings只读字段信息 node -e const fs require(fs); const map JSON.parse(fs.readFileSync(process.argv[1], utf8)); const sc map.sourcesContent; console.log(sources:, map.sources.length); console.log(sourcesContent:, sc ? sc.length : undefined); if (sc) { const empty sc.filter(v !v).length; console.log(empty entries:, empty); console.log(sample:, sc.find(Boolean)?.slice(0, 80)); } /path/to/cli.js.map这个脚本把两个关键数组的长度打出来并统计空条目。正常情况下sources和sourcesContent长度一致、空条目为零、sample 里能看到import、export这类 TypeScript 源码开头。如果打印出来的是undefined或者空条目占了大半后面就不能依赖直读方案得考虑换一个带完整sourcesContent的版本或者接受只能做堆栈映射、还原不出全量源码的现实。这一步值得花两分钟因为它直接决定整个方案走哪条路也能避免后续脚本白跑一趟。4. 还原落盘最小直读脚本、source-map 库写法与产物校验4.1 不解析 mappings 的直读脚本最短路径把源码写回磁盘确认sourcesContent完整后还原本身出乎意料地简单。不需要引入任何第三方库读 JSON、按下标配对路径和内容、写文件三步走完。我把脚本写成一个通用工具传入一个或多个 map 文件路径即可同时内置了路径清洗和越界保护。// restore-sourcemap.js —— 直读 sourcesContent 批量还原源码 const fs require(fs); const path require(path); const OUT_ROOT path.resolve(process.env.OUT_DIR || restored); const files process.argv.slice(2); for (const mapFile of files) { const map JSON.parse(fs.readFileSync(mapFile, utf8)); const { sources, sourcesContent } map; if (!Array.isArray(sourcesContent)) { console.error([skip] ${mapFile}: no sourcesContent); continue; } sources.forEach((src, i) { const content sourcesContent[i]; if (typeof content ! string) return; // 空条目跳过 const outPath safeResolve(src, OUT_ROOT); if (!outPath) return; fs.mkdirSync(path.dirname(outPath), { recursive: true }); fs.writeFileSync(outPath, content, utf8); }); console.log([done] ${mapFile} - ${OUT_ROOT}); } // 把 sources 里的路径清洗后收敛到 OUT_ROOT 下防止路径逃逸 function safeResolve(src, root) { let p src .replace(/^webpack:\/\/[^/]*\//, ) // 去掉协议头和包名 .replace(/^file:\/\//, ) // 去掉 file:// 前缀 .replace(/^\.\//, ); // 去掉开头的 ./ const abs path.resolve(root, p); if (!abs.startsWith(root path.sep) abs ! root) { console.warn([warn] path escapes root: ${src}); return null; } return abs; }逻辑说明脚本核心是sources.forEach那段——sources和sourcesContent是等长数组下标一致直接把第 i 个内容写到第 i 个路径上。safeResolve负责路径清洗压缩包里 sources 往往带着webpack://claude-code/./src/xxx.ts这种前缀第一步把协议头和包名剥掉剩下的./src/xxx.ts再落盘到输出根目录最后用startsWith(root)判断是否逃逸防止 sources 里出现../../把文件写到还原目录之外。参数说明OUT_DIR环境变量控制输出目录默认restored命令行传入多个 map 文件时脚本逐个处理每个 map 的输出都收敛在同一根目录下。这个直读方案的快就在于跳过了整个 mappings 解析。对一个几十 MB 的 mapJSON.parse本身是主要耗时解析 VLQ 映射反而更慢更吃内存。4.2 需要堆栈反查时再上 source-map 库originalPositionFor 的用法直读方案适合批量落盘但如果你后续要做压缩代码行号 → 原始代码行号的映射就需要真正解析 mappings。标准做法是用source-map这个 npm 库它把 VLQ 解码、索引构建都封装好了。// map-stack.js —— 用 source-map 解析 map演示单点映射 const { SourceMapConsumer } require(source-map); const fs require(fs); const mapData JSON.parse(fs.readFileSync(process.argv[2], utf8)); SourceMapConsumer.with(mapData, null, (consumer) { // 示例把压缩产物第 100 行第 5 列映射回原始位置 const pos consumer.originalPositionFor({ line: 100, column: 5 }); console.log(original:, pos); // 也可以像直读方案一样导出全部 sourcesContent consumer.sources.forEach((src, i) { if (consumer.sourcesContent[i]) { // 写盘逻辑复用 4.1 的 safeResolve此处省略 } }); }).catch((err) console.error(parse failed:, err.message));逻辑说明SourceMapConsumer.with是库推荐的入口传入 map 的 JSON 对象回调里拿到 consumer 实例。originalPositionFor接收压缩产物的行列号返回{ source, line, column, name }这样的结构这就是运行时堆栈反查的基础。参数说明line和column均从 1 开始计数部分工具返回 0 基结果对齐时注意换算回调里同样可以读取consumer.sourcesContent做导出和直读脚本的差异是这里额外解析了 mappings内存开销约为 map 本身的两到三倍。如果只是还原源码没必要走这条路如果要做后续调试这条路能省去自己解析 VLQ 的工夫代价是 Node 堆要留足。4.3 校验还原产物文件数、入口、关键符号三连查落盘之后别急着收工先校验一次还原产物是否可信。校验分三层第一层看文件数量和路径结构是否符合预期第二层看是否有入口文件能对应上 cli.js 的启动逻辑第三层抽查几个关键符号确认代码不是占位符。我用一条命令完成前两层。# 统计还原出的文件数与非空文件数 find restored -type f | wc -l find restored -type f -size 0c | wc -l # 查找入口类文件通常是 cli.ts / main.ts / command 相关文件 find restored -name cli.ts -o -name main.ts | head -20文件总数和非空文件数如果相差很大说明有一部分 sources 对应的sourcesContent是空的要返回去检查预检步骤里的 empty entries。入口文件的存在与否是更强的信号claude-code 这种 CLI 工具的源码必然有一个启动入口找到它之后打开看如果看到参数解析、命令分发、主流程调用这些内容还原基本就成功了。最后再抽查一个模块文件找一个你熟悉的函数名在还原产物里追踪它的调用链确认代码是完整的、可读的。这三层都过了还原产物才能作为后续分析的基础否则就要回到第 3 章的预检重新排查。5. 还原避坑记录五个真实翻车现场与排查方法5.1 现象sources 有值sourcesContent 全为空还原出来一堆空文件原因不是所有发行版的 map 都带sourcesContent。部分构建配置会开hidden-source-map或为了省体积把内容剥离只保留定位映射。空文件比字段缺失更难提前发现因为数组长度对得上脚本不会报错。解决还原前先跑 3.3 的预检脚本重点关注 empty entries 数量如果为空放弃直读方案要么换一个带完整sourcesContent的版本要么接受只做堆栈映射、不做全量还原的降级方案。不要试图从 mappings 里反推源码那是把几个月的工时砸进无底洞。5.2 现象还原出的文件路径乱飞出现 restored/../../ 越权目录甚至写到还原目录之外原因sources 里的路径不是为落盘设计的。它可能是webpack://包名/./src/a.ts也可能是../node_modules/...这种相对路径直接path.resolve(mapFilePath, src)时..会被解析成目录上跳。解决所有路径先做协议头剥离和../收敛再用startsWith(root)做越界判断越界的文件直接丢弃并在日志里警告。我用 4.1 里safeResolve就是这个目的实际项目里我还加过一层把node_modules前缀的路径统一重写到vendor/目录下保持还原目录整洁方便区分第三方依赖和本体代码。5.3 现象Node 进程解析 map 时内存暴涨直接 OOM小机器上第一次跑就崩原因JSON.parse要一次性把整个 map 读进内存SourceMapConsumer又要构建一份映射索引两个大对象叠加几百 MB 的 map 能吃掉 2GB 以上的堆。解决纯还原场景不用SourceMapConsumer用原始 JSON 直读只访问sources和sourcesContent两个字符串数组如果必须用库启动时给 Node 显式加大堆node --max-old-space-size4096 map-stack.js cli.js.map。另外优先单独处理大 map而不是一次性把所有 map 文件传给同一个进程失败时也更好定位是哪一个文件的问题。5.4 现象还原出来的是 TypeScript对照着看逻辑总觉得和实际行为对不上原因map 记录的是构建时的原始源码而运行的是经过转译、内联、摇树之后的 JS。TypeScript 的枚举、装饰器、泛型在转译后形态完全不同被摇树删掉的模块源码里还在但运行时根本不存在。解决把还原产物当成阅读用参考实现排查问题时仍然以运行时行为和实际堆栈为准。想看某个函数到底怎么执行不要只盯着还原的 TS 看用第 6 章的反查手法把运行时行号映射回来两者对照才可靠。5.5 现象map 与发布产物不一致堆栈反查落到了错误位置原因source map 对应的可能是构建缓存或发布流水线里某一跳的产物和最终发布出去的 cli.js 不是完全同一份代码。发布环节偶尔会出现 map 更新滞后导致 mappings 对不上实际产物。解决拿到 map 后先做配套性检查直接拿 cli.js 里某一段特征字符串去源码里 grep对得上再深入分析对不上的 map 宁可不用也别硬着头皮往下走否则所有结论都建在错误的地基上排查问题会越排越偏。6. 进阶验证把运行时堆栈映射回还原源码确认整套还原可信还原完源码最有说服力的验证不是文件能打开而是把运行时报错的行号映射回还原后的源码看能不能精准落到具体的函数和参数上。做法很简单让 claude-code 在某个场景下抛一个错误拿到压缩代码里的行号列号然后调用SourceMapConsumer的originalPositionFor把还原后的源码文件和行列打印出来。如果还原产物里能定位到那个函数说明 map 和产物是配套的整个还原链路可信。// verify-map.js —— 传入 cli.js 的报错行列反查原始位置 const { SourceMapConsumer } require(source-map); const fs require(fs); const mapData JSON.parse(fs.readFileSync(cli.js.map, utf8)); SourceMapConsumer.with(mapData, null, (consumer) { const pos consumer.originalPositionFor({ line: Number(process.argv[2]), column: Number(process.argv[3]) }); console.log(pos.source, ${pos.line}:${pos.column}, pos.name || ); });跑一次之后再去还原产物里打开那个文件定位到对应行如果上下文和报错信息对得上这个项目就值得你投入研究。我现在的习惯是凡是拿到带 map 的工具包先还原、再抽查三处运行时堆栈、最后把还原结果单独备份一份免得包升级后文件被覆盖。往后你分析任何闭源打包的 Node 工具这条 source-map 还原路径都能复用省下的摸索时间很可观。希望帮到你。本文还有配套的精品资源点击获取