AnandPilania/sourcemap-extract

# sourcemap-extract 从 JavaScript/CSS source map 还原原始源文件。 实现了 **[ECMA-426](https://tc39.es/ecma426/)**（第 1 版，2024 年 12 月）—— 官方的 source map 标准。 ## 快速开始 ``` # 无需安装 npx sourcemap-extract -o ./src dist/bundle.js.map # 或全局安装 npm install -g sourcemap-extract sourcemap-extract -o ./src dist/bundle.js.map ``` ## 命令行用法 ``` sourcemap-extract [options] Inputs Any source map file A bundled file with an embedded base64 sourceMappingURL Recursively finds and processes every .map file inside - Reads source map JSON from stdin ``` ### 选项 | 标志 | 描述 | | ----------------- | ------------------------------------------------------------------------------------------- | | `-o, --out ` | 输出目录（默认：`./sourcemap-out`） | | `-f, --force` | 覆盖已存在的文件 | | `-n, --dry-run` | 打印将要写入的内容而不实际写入 | | `-v, --verbose` | 在提取期间记录每个文件路径 | | `--skip-ignored` | 跳过在 `ignoreList` / `x_google_ignoreList` 中列出的源（第三方/node_modules 代码） | | `-h, --help` | 显示帮助 | ### 示例 ``` # 单个 map 文件 npx sourcemap-extract -o ./src dist/bundle.js.map # 带有嵌入 sourceMappingURL 的生成文件 npx sourcemap-extract -o ./src dist/bundle.js # 整个 dist 文件夹 — 递归处理每个 .map 文件 npx sourcemap-extract -o ./src ./dist # 预览而不写入 npx sourcemap-extract --dry-run ./dist # 跳过第三方代码 (ignoreList) npx sourcemap-extract --skip-ignored -o ./src dist/bundle.js.map # 强制覆盖 + 详细输出 npx sourcemap-extract -f -v -o ./src dist/bundle.js.map # stdin cat bundle.js.map | npx sourcemap-extract -o ./src - ``` ## 编程 API ``` const { parseSourceMap, // parse JSON → source entries extractFromJson, // extract to disk from JSON string extractFromFile, // extract to disk from file path findMapFiles, // recursively find .map files in a directory resolveSourceURL, // resolve a single sourceRoot + source URL sanitizePath, // sanitise a resolved path for safe disk writes } = require('sourcemap-extract'); ``` ### `parseSourceMap(json)` 解析 source map JSON 字符串。返回源条目的数组。 ``` const entries = parseSourceMap(fs.readFileSync('bundle.js.map', 'utf8')); // [ // { name: 'src/App.tsx', content: '...', ignored: false }, // { name: 'src/utils.ts', content: '...', ignored: false }, // { name: null, content: null, ignored: true }, // null-named source // ] ``` 每个条目： | 字段 | 类型 | 描述 | | --------- | ---------------- | ------------------------------------------------------------------- | | `name` | `string \| null` | 解析后的源路径，如果源条目为 `null` 则为 `null` | | `content` | `string \| null` | 来自 `sourcesContent` 的原始源代码文本，如果缺失则为 `null` | | `ignored` | `boolean` | 如果索引出现在 `ignoreList` / `x_google_ignoreList` 中则为 `true` | ### `extractFromJson(mapJson, outDir, options?)` 从原始 JSON 字符串中提取源文件并写入磁盘。 ``` const result = extractFromJson(mapJson, './src', { force : false, // overwrite existing files dryRun : false, // don't write, just report skipIgnored: false, // skip ignoreList sources verbose : false, // log per-file activity }); // result: { total, written, failed, skipped, noContent, ignored, planned?, error? } ``` 在 `dryRun` 模式下，`result.planned` 是一个包含将要写入的路径的数组；`result.written` 始终为 `0`。 ### `extractFromFile(filePath, outDir, options?)` 便捷封装 —— 先从磁盘读取文件，然后调用 `extractFromJson`。 接受 `.map`/`.json` 文件或带有内嵌 base64 `sourceMappingURL` 的生成文件。 ### `findMapFiles(dir)` 递归返回 `dir` 目录中的每个 `.map` 文件路径（匹配 `*.js.map`、`*.css.map`、`*.ts.map`、`*.wasm.map`、`*.map` 等）。 ## ECMA-426 合规性 | 要求 | 状态 | | ------------------------------------------------- | ------ | | `sources` 条目可以为 `null` | ✅ | | `sourcesContent` 长度短于 `sources` | ✅ | | `sourcesContent` 条目可以为 `null` | ✅ | | `ignoreList`（标准字段） | ✅ | | `x_google_ignoreList`（已弃用的别名） | ✅ | | 分段 map（`{ sections: [] }`） | ✅ | | JSON 解析前剥离 UTF-8 BOM | ✅ | | `sourceRoot` URL 样式拼接（仅限相对路径） | ✅ | ### 自动剥离的 Bundler URL 方案 `webpack://`、`webpack-internal:///`、`ng://`、`vite://`、`turbopack://[project]/` 以及任何通用的 `protocol://origin/` 前缀。 ## 路径安全性 所有输出路径在写入前都会被净化处理： - 移除开头的 `../` 遍历序列 - 绝对路径（`/…`、`C:\…`）将转换为相对路径 - 剥离查询字符串和片段标识符 - 跳过重复的源→目标冲突（保留第一个） 没有任何文件会被写入到指定的输出目录之外。 ## 许可证 MIT

标签：CMS安全, CSS, ECMA-426, GNU通用公共许可证, JavaScript, MITM代理, Node.js, npm, npx, Source Map, Web安全, 云安全监控, 云资产清单, 代码混淆, 前端安全, 数据可视化, 源码提取, 源码还原, 白盒审计, 自定义脚本, 蓝队分析, 逆向工程, 静态分析