如何用 verify-source-map 脚本验证 esbuild 生成的 sourcemap 正确性【免费下载链接】esbuildAn extremely fast bundler for the web项目地址: https://gitcode.com/GitHub_Trending/es/esbuild当你修改了 esbuild 自身与 sourcemap 相关的代码或想确认某个构建出来的 esbuild 生成的 sourcemap 是否可信时仓库自带一个专门的验证脚本scripts/verify-source-map.js并接入了 Makefile 的verify-source-map目标。这个脚本会内置构造一批测试输入JS 打包、CSS、TypeScript、stdin、代码拆分、unicode、第三方嵌套 sourcemap 等用 Go 编译本地源码得到 esbuild 可执行文件后逐个运行并生成 sourcemap再对映射逐项校验全部通过时输出✅ verify source map passed。准备条件在 esbuild 仓库的工作副本中操作。脚本会编译./cmd/esbuild、读取version.txt临时目录创建在scripts/下必须在仓库根目录运行。已安装 Go脚本内部调用go build编译 esbuild 二进制开发文档 中编译 esbuild一节同样以安装 Go 为前提。仓库在 go.version 中记录了开发所用 Go 版本当前为 1.26.5check-go-version目标会在发布前核对它verify-source-map本身不强制该版本但建议保持一致。已安装 Node用于执行npm ci和运行脚本。脚本自身依赖在 scripts/package.json 中声明关键是source-map0.7.4提供用来查映射的SourceMapConsumer以及complex测试用例要打包的fuse.js和react。Makefile 里的scripts/node_modules目标就是cd scripts npm ci。运行验证主路径是在仓库根目录执行make verify-source-mapMakefile 中该目标实际依次做三件事依赖version-go运行node scripts/esbuild.js --update-version-go把version.txt的版本同步进cmd/esbuild/version.go仅在内容不一致时修改该文件依赖scripts/node_modules运行cd scripts npm ci安装测试依赖运行node scripts/esbuild.js npm/esbuild/package.json --version同样只在版本不一致时修改npm/esbuild/package.json最后执行node scripts/verify-source-map.js。没有make时也可以手动执行效果等价省略的只是前两条版本同步步骤不影响映射验证本身cd scripts npm ci cd .. node scripts/verify-source-map.js两种方式下脚本都会先调用 scripts/esbuild.js 中的buildBinary()它在仓库根目录执行go build -ldflags-s -w -buildid -buildvcsfalse -trimpath ./cmd/esbuild生成esbuild可执行文件Windows 上是esbuild.exe后续所有测试用例都用它。也就是说验证对象是你当前这份被修改过的源码而不是任何已发布的二进制。需要知晓的副作用该流程会在你的本地检出中可能改写cmd/esbuild/version.go和npm/esbuild/package.json两个文件仅当内容与version.txt不一致时在仓库根目录生成esbuild可执行文件并创建/删除scripts/.verify-source-map临时目录。脚本具体校验什么scripts/verify-source-map.js 中每个测试用例是一组脚本内置的小源文件例如a.js→b-dir/b.js→b-dir/c-dir/c.js的多级导入链或一个内联 base64 sourcemap 的单文件。main()把每个测试用例按crlf是否把换行改成 CRLF与minify是否追加--minify的四种组合各跑一遍每次调用 esbuild 时都带--sourcemap --log-levelwarning再叠加该用例专属参数如--bundle、--outdir. --bundle --splitting --formatesm、--jsxautomatic等。每次运行都会做以下检查映射注释检查输出文件必须含# sourceMappingURL...注释stdin 用例则检查 stdout 中的内联sourceMappingURLdata:application/json;base64,反向映射检查对每个预置的检索串如a0、b0先定位它在生成代码中的位置再用SourceMapConsumer.originalPositionFor查回原始位置要求source、line、column与它在原始源文件中的真实位置完全一致正向映射检查用allGeneratedPositionsFor从原始位置反查生成位置要求结果包含刚才那个位置sources 去重检查sourcemap 的sources数组不允许出现重复项逐位置覆盖检查仅非 bundle 模式输出文件除 hashbang 行和 sourcemap 注释行外每一行每一列都必须能映射到原始位置嵌套链式检查把第一次的产物作为输入另加一个extra文件按三种不同导入顺序再用--bundle --sourcemap --formatesm重新打包并重复上述映射检查——这验证 esbuild 对已有 sourcemap 的链式重编码是否正确names 字段检查专门的checkNames流程校验源码中以/**/标注的标识符名称包括--mangle-props重命名后的属性名能正确取出并往返一致。测试用例类别覆盖CommonJS/ES6 打包、不连续文件、TypeScript 运行时函数、stdin、空文件、非 JS 文件.txt、代码拆分、unicode 与--charsetutf8、含部分映射partial mappings的 sourcemap、CSS 打包、JSX automatic runtime、第三方工具如 Clojure 的 shadow-cljs生成的 indexed sourcemap、绝对路径、嵌套 sourcemap 中sourcesContent缺失或为 null 的情况以及若干已知问题的回归issue-4070、issue-4075、issue-4080、issue-4104、issue-4169等命名的用例。其中complex用例会打包scripts/node_modules下的fuse.js与react并校验其中的嵌套 sourcemap这也是npm ci必须装这两个依赖的原因。如何判断结果脚本最终只有两种输出全部通过最后一行是✅ verify source map passed进程退出码为 0临时目录scripts/.verify-source-map被删除存在失败项先逐条打印❌ [测试用例名] 具体错误最后一行是❌ verify source map failed退出码为 1。具体错误文案由脚本内的检查函数直接给出用于定位问题例如expected source: a.js, observed source: ...——映射查回的 source 不对expected original position: {...}, observed original position: {...}——映射到的原始位置不对expected generated position: ..., observed generated positions: [...]——正向映射结果不对missing location for line 12 and column 5——非 bundle 模式下某生成位置完全没有原始位置out.js file must link to out.js.map——输出中的映射注释不对Duplicate source ... found in source map——sourcemap 中 source 重复。某个用例失败时它在scripts/.verify-source-map下的临时目录不会被删除通过的会删。你可以直接打开对应用例目录里的输入文件、out.js与out.js.map对照sources、sourcesContent和mappings手动核查修复代码后重跑make verify-source-map。与其他测试的关系Makefile 中的注释标明verify-source-map属于test-common目标组即make test会运行、面向开发阶段的测试。只验证 sourcemap 行为时单独跑make verify-source-map即可若需要完整开发测试Go 测试、end-to-end 测试、JS API 测试等再使用make test。【免费下载链接】esbuildAn extremely fast bundler for the web项目地址: https://gitcode.com/GitHub_Trending/es/esbuild创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考