N ECat文档中心

ECat符号文件上传工具使用文档#

一、符号文件简介#

  1. 安卓Native符号文件

    Native符号文件是函数与对应偏移地址的映射表。发生Native崩溃时，原始的崩溃栈只有模块名和偏移地址。将so文件对应的符号文件上传至服务器后，偏移地址会被还原为对应函数。

  2. 安卓Proguard Mapping文件

    安卓项目使用Proguard混淆Java代码后，发生Java崩溃时，得到的崩溃栈为混淆后的类和函数。将Mapping文件上传至服务器后，将还原为混淆前的类和函数。

  3. iOS符号文件

    iOS符号文件与安卓Native符号文件类似，格式有所区别。

  4. 鸿蒙符号文件

    4.1 鸿蒙Native符号文件

    ​ 鸿蒙和安卓的Native层都是基于Linux的，因此鸿蒙与安卓的Native符号文件类型相同

    4.2 鸿蒙SourceMaps和nameCache文件

    使用ArkTs开发时，若配置了混淆规则，则生成的应用中，源码的文件名、类、属性等名称将被混淆。混淆后会在工程中生成两个文件：

    ​ sourceMaps.map：源文件映射表

    ​ nameCache.json：名称映射表

    以上两个文件可以用于还原ArkTs函数栈

  5. Windows符号文件

    PDB文件是由Visual Studio在编译链接时生成的文件。主要存储了VS调试程序时所需要的基本信息，主要包括源文件名、变量名、函数名、对应的行号等等。

二、符号文件生成#

2.1 安卓Native符号文件#

安卓Native符号文件由未strip的so生成，上传时必须保证与线上版本一致。

对应so文件路径：

  1. 原生Android Studio工程

    工程目录/build/intermediates/cmake/release/obj/

    或

    工程目录/build/intermediates/merged_native_libs/release/out/lib/

  2. Unity项目

    工程目录/Temp/gradleOut/unityLibrary/build/intermediates/merged_jni_libs/release/out/

    若启用il2cpp且配置Create symbols.zip：工程目录/**.symbols.zip（支持批量上传）

  3. Cocos2dx安卓工程

    工程目录/frameworks/runtime-src/proj.android/app/build/intermediates/ndkBuild/release/obj/local/

    或

    工程目录/frameworks/runtime-src/proj.android/app/build/intermediates/transforms/mergeJniLibs/release/0/lib/

2.2 Proguard Mapping文件#

直接上传该文件，位置：工程目录/build/outputs/mapping/release/mapping.txt

2.3 iOS 符号文件#

由.dSYM文件生成生成，dSYM需要在Xcode中进行以下配置后才能生成：

Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

dSYM与app文件在同一个目录下。

2.4 鸿蒙符号文件#

2.4.1 Native#

  1. DevEco Studio

    工程目录/build/default/intermediates/cmake/default/obj/

  2. 团结引擎

    工程目录/StagingArea/OpenHarmonyAppTemplate/entry/build/default/intermediates/cmake/default/obj/

    若配置Create symbols.zip：工程目录/**.symbols.zip

2.4.2 sourceMaps & nameCache#

工程目录/build/default/cache/default/default@CompileArkTS/esmodule/release/sourceMaps.map

工程目录/build/default/cache/default/default@CompileArkTS/esmodule/release/obfuscation/nameCache.json

2.5 Windows符号文件#

  1. Visual Studio

    一般与dll或exe同一目录

  2. Unity

    需要在Build Settings页面勾选Copy PDB files，再Build。

    与exe在同一目录下

注意：

  1. pdb文件名称必须与真实dll的名称一致。若不一致请手动修改，否则无法还原符号
  2. 上传64位符号文件时，尽量确保pdb与对应dll或exe在同一目录下，可以增加更详细的符号信息

三、上传方法#

3.1 环境准备#

  • 安装python（版本2.7以上），并安装requests库（pip install requests）
  • Windows 使用cmd（不能使用PowerShell）
  • iOS .dSYM符号只能在Mac上传
  • 关闭代理

3.2 使用方法#

  1. 解压工具压缩包，进入工具目录

  2. 使用以下命令查看说明：

python ECatSymbolUploader.py -h
  1. 参数说明：
参数 说明
-i (必填)appId
-k (必填)appKey
-v (必填)必须SDK中设置的appVersion相同
-t (必填)文件类型
-tag (选填)自定义标签
-p (必填)文件路径：.pdb/.so/.txt/.symbols.zip/.dSYM/.map/.json

​ -t和-p参数说明

-t 符号类型 -p 文件路径的可选类型
1 pdb/so 文件、目录
2 JavaMapping 文件
4 iOS .dSYM 文件、目录
5 Unity symbols.zip(仅安卓) zip
6 鸿蒙so 文件、目录、zip
7 鸿蒙soucemap 文件

备注：

1）-p若为目录，则遍历目录下同一符号类型文件；若为zip，则遍历解压后目录中的同一符号类型文件。

2）上传JavaMapping和鸿蒙sourceMap时，-v参数必须与SDK初始化函数中的appVersion一致，否则无法还原函数栈。

3）上传so时，文件名必须与app中的真实so文件名相同，否则无法还原函数栈。

  1. 执行示例：
python ECatSymbolUploader.py -i appId -k appKey -v V1.1 -t 1 -p ./libECat.so

建议将工具集成到打包环境中，构建测试和正式版本的release包时，自动上传符号文件