Documentation
¶
Overview ¶
Package sourcemap 提供 source map（v3）的解析与原始源码还原功能。
还原策略采用"sourcesContent 优先 + mappings 回退"两者结合：
- 优先路径：直接读取 source map 的 sourcesContent 字段（打包前的原始明文源码）， 按 sources 路径写成分离的源文件。速度快、准确，但依赖打包工具保留了该字段。
- 回退路径：当 sourcesContent 缺失或对应元素为空时，解析 mappings（VLQ 编码）， 把压缩后的 JS 按 source 索引切分重组为可读片段。注意：mappings 只能提供位置 映射，无法 100% 还原原文，回退产物会在文件头加注释标注"非完整源码"。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizeSourcePath ¶
NormalizeSourcePath 规范化 source map 中 sources 字段的路径， 使其可作为安全的相对文件路径写入磁盘，保留原始目录层级。
输入示例：
webpack:///./src/App.jsx -> src/App.jsx webpack:///webpack/bootstrap -> webpack/bootstrap webpack-internal:///./node_modules -> node_modules/foo.js ./src/utils.js -> src/utils.js /static/js/app.js -> static/js/app.js ../../../../node_modules/foo.js -> node_modules/foo.js (.. 按相对路径回溯) ../../etc/passwd -> etc/passwd (超出根的 .. 被丢弃，不逃逸) file:///home/user/a.js -> home/user/a.js
sourceRoot 非空时会作为前缀拼接到规范化后的路径前（同样经过清理）。 返回空字符串表示路径无法规范化（如纯 scheme 无实际路径）。
func SafeFilePath ¶
SafeFilePath 将规范化的 source path 转为当前 OS 的文件路径 确保结果始终是相对路径，不会逃逸到上级目录
Types ¶
type Mapping ¶
type Mapping struct {
// GeneratedLine 生成代码（压缩后）的行号，0-based
GeneratedLine int
// GeneratedColumn 生成代码的列号，0-based
GeneratedColumn int
// SourceIndex sources 数组的索引（-1 表示无）
SourceIndex int
// SourceLine 原始源码的行号，0-based（-1 表示无）
SourceLine int
// SourceColumn 原始源码的列号，0-based（-1 表示无）
SourceColumn int
// NameIndex names 数组的索引（-1 表示无）
NameIndex int
}
Mapping 表示 source map mappings 中的单条映射
func ParseMappings ¶
ParseMappings 解析 source map 的 mappings 字符串 mappings 字符串格式：行之间用 ; 分隔，段之间用 , 分隔 每个段是 1、4 或 5 个 VLQ 编码的值：
- 1 个值：GeneratedColumn（与前一段同 source）
- 4 个值：GeneratedColumn, SourceIndex, SourceLine, SourceColumn
- 5 个值：GeneratedColumn, SourceIndex, SourceLine, SourceColumn, NameIndex
除 GeneratedColumn 外，所有值都是相对前一段的增量（跨行也保持增量）
type RestoreMode ¶
type RestoreMode int
RestoreMode 标记还原出的源文件来源
const ( // RestoreModeNone 未还原（无可用内容） RestoreModeNone RestoreMode = iota // RestoreModeSourcesContent 来自 sourcesContent 字段（完整原文） RestoreModeSourcesContent // RestoreModeMappings 来自 mappings 重组（非完整源码） RestoreModeMappings )
func (RestoreMode) String ¶
func (m RestoreMode) String() string
String 实现 RestoreMode 的字符串表示，便于调试输出
type SourceFile ¶
type SourceFile struct {
// Path 规范化后的相对路径（如 src/App.jsx）
Path string
// Content 文件内容
Content []byte
// Mode 还原方式
Mode RestoreMode
}
SourceFile 还原出的单个源文件
func RestoreFiles ¶
func RestoreFiles(sm *SourceMap, minifiedContent []byte) ([]SourceFile, error)
RestoreFiles 从 source map 还原出原始源文件列表。
还原顺序：
- 优先用 sourcesContent（完整原文）
- 若 sourcesContent 对应元素为空，且 minifiedContent 非空，则用 mappings 重组压缩 JS 片段作为回退
参数 minifiedContent 是压缩后的 JS 内容，仅在 sourcesContent 缺失时用于回退。 若 sourcesContent 完整，可传 nil。
type SourceMap ¶
type SourceMap struct {
// Version source map 规范版本（通常为 3）
Version int `json:"version"`
// File 生成文件（压缩后的 JS）的名称
File string `json:"file,omitempty"`
// SourceRoot 所有 sources 路径的前缀，用于解析相对路径
SourceRoot string `json:"sourceRoot,omitempty"`
// Sources 原始源文件路径列表
Sources []string `json:"sources"`
// SourcesContent 原始源文件内容列表，与 sources 一一对应；
// 可能为 null、缺失、或某些元素为 null
SourcesContent []string `json:"sourcesContent,omitempty"`
// Names mappings 中引用的标识符名称列表
Names []string `json:"names,omitempty"`
// Mappings VLQ 编码的位置映射字符串
Mappings string `json:"mappings"`
}
SourceMap 对应 source map v3 规范的 JSON 结构 参考：https://sourcemaps.info/spec.html
func (*SourceMap) HasSourcesContent ¶
HasSourcesContent 判断 source map 是否包含可用的 sourcesContent 返回 true 当且仅当至少有一个 sourcesContent 元素非空
Source Files