154 lines
4.2 KiB
Markdown
154 lines
4.2 KiB
Markdown
# 堆栈解析工具 (hstack)
|
|
|
|
hstack 是用于将 Release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台。
|
|
|
|
## 命令格式
|
|
|
|
```bash
|
|
hstack [options]
|
|
```
|
|
|
|
## 命令参数
|
|
|
|
| 参数 | 说明 |
|
|
|------|------|
|
|
| `-i, --input` | 指定 crash 文件归档目录 |
|
|
| `-c, --crash` | 指定一条 crash 堆栈 |
|
|
| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） |
|
|
| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 |
|
|
| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 |
|
|
| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 |
|
|
| `-v, --version` | 查看版本 |
|
|
| `-h, --help` | 查询帮助 |
|
|
|
|
## 参数约束
|
|
|
|
- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项**
|
|
- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项**
|
|
- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件
|
|
- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? ``
|
|
|
|
## 环境配置
|
|
|
|
1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量
|
|
2. 配置 Node.js 到环境变量
|
|
3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH`
|
|
|
|
## 使用示例
|
|
|
|
### 解析 crash 文件目录
|
|
|
|
```bash
|
|
# 完整解析命令
|
|
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir
|
|
|
|
# 仅使用 sourcemap 解析 (ArkTS)
|
|
hstack -i crashDir -o outputDir -s sourcemapDir
|
|
|
|
# 仅使用 so 文件解析 (C++)
|
|
hstack -i crashDir -o outputDir --so soDir
|
|
|
|
# 包含方法名还原
|
|
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
|
|
```
|
|
|
|
### 解析单条堆栈
|
|
|
|
```bash
|
|
# 输出到控制台
|
|
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir
|
|
|
|
# 输出到文件
|
|
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt
|
|
```
|
|
|
|
## 输出说明
|
|
|
|
- 解析结果输出到 `-o` 指定目录，文件以原始 crash 文件名加 `_` 前缀命名
|
|
- 不指定 `-o` 时：
|
|
- 使用 `-i` 输入：输出到 crashDir 目录
|
|
- 使用 `-c` 输入：直接输出到控制台
|
|
|
|
## 文件获取
|
|
|
|
### Sourcemap 文件
|
|
|
|
构建产物中的 sourcemap 文件，包含：
|
|
- 路径信息映射
|
|
- 行列号映射 (mappings 字段)
|
|
- package-info 信息
|
|
|
|
### NameCache 文件
|
|
|
|
构建产物中的 nameCache 文件，包含：
|
|
- `IdentifierCache`: 标识符混淆映射
|
|
- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"`
|
|
|
|
### Shared Object (.so) 文件
|
|
|
|
构建 Release 应用时，默认 so 文件不包含符号表。如需生成包含符号表的 so 文件，在模块 `build-profile.json5` 中配置：
|
|
|
|
```json5
|
|
{
|
|
"buildOption": {
|
|
"externalNativeOptions": {
|
|
"arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 堆栈解析原理
|
|
|
|
### Crash 堆栈格式
|
|
|
|
```
|
|
at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58)
|
|
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
|
|
```
|
|
|
|
路径格式：`引用方packageName|被引用方packageName|version|源码相对路径`
|
|
|
|
### 解析步骤
|
|
|
|
1. **根据路径信息找到 sourcemap**
|
|
- 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段
|
|
|
|
2. **利用 sourcemap 还原路径和行列号**
|
|
- 根据 `sources` 和 `mappings` 字段解析
|
|
- 如包含 `package-info`，可进行二次解析获取更准确的源码位置
|
|
|
|
3. **利用 nameCache 还原方法名**
|
|
- 查找混淆后方法名对应的所有条目
|
|
- 根据还原后的行号范围匹配正确的源码方法名
|
|
|
|
### 解析示例
|
|
|
|
原始堆栈：
|
|
```
|
|
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
|
|
```
|
|
|
|
还原后：
|
|
```
|
|
at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)
|
|
```
|
|
|
|
## CI/CD 集成
|
|
|
|
```bash
|
|
# 自动化解析脚本示例
|
|
hstack \
|
|
-i ./crash-logs \
|
|
-o ./parsed-logs \
|
|
-s ./build/sourcemap \
|
|
--so ./build/libs \
|
|
-n ./build/nameCache
|
|
```
|
|
|
|
## 常见问题
|
|
|
|
1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数
|
|
2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置
|
|
3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项
|