Source Map

对于前端应用来说，JS错误的发生直接影响前端应用的质量，因此对于JS错误的定位及诊断显得尤为重要。基调听云提供了SourceMap上传来还原代码真正的错误位置，还原JS错误现场。这样使得开发者能够迅速定位出错的源代码位置以及相应的代码块。

什么是Source Map

Source Map是一个存储源代码与编译代码对应位置映射的信息文件，便于开发人员定位上述代码错误。实际上，它就是一个JSON键值对，利用VLQ编码与特定的规则存储位置信息。简而言之，可以理解为Source Map在处理前的代码和处理后的代码之间搭建了一座桥梁。

Source Map支持通过CLI方式上传，Tingyun CLI是一个CLI程序，是上传Source Map的主要方式。小程序需要上传两个Source Map文件：微信平台Source Map和程序压缩的Source Map。

安装

npm安装

当前工作目录安装：

进入前端工程目录，安装CLI包。
```
npm install @tingyun-common/cli
```
验证安装成功。
```
./node_modules/.bin/tingyun-cli -v
```

如果终端中打印tingyun-cli版本证明安装成功。

全局安装：

安装。
```
npm install -g @tingyun-common/cli --unsafe-perm
```
需要确保有权限访问全局的node_modules目录，如果在Linux、Mac环境遇到权限问题，建议使用root安装。
```
sudo npm install -g @tingyun-common/cli --unsafe-perm
```
验证安装成功。
```
tingyun-cli -v
```

如果终端中打印tingyun-cli版本证明安装成功。

其他npm安装配置

配置CLI下载地址：

--tingyuncli_cdnurl=<下载地址根路径>

使用示例：

npm install @tingyun-common/cli --tingyuncli_cdnurl=http://example.com/path

手动下载可执行文件

可以在基调听云文件下载服务器查看tingyun-cli已经发布的版本，并下载到Linux、Mac、Windows平台的可执行文件。下载之后可以重命名为tingyun-cli.exe或tingyun-cli来使用。注意可执行文件是CLI程序，需要在终端中使用。

使用

初始化。

Tingyun CLI依赖于配置文件来使用，配置文件名为.tingyunclirc或.tingyunclirc.toml，格式为toml格式。配置文件信息可以在应用设置中复制或者通过运行tingyun-cli init提供的交互式信息输入工具来初始化。在使用CLI上传Source Map之前，需要保证当前目录或用户目录存在配置文件。
- 在项目工作目录中执行初始化命令生成配置文件.tingyunclirc.toml。
```
tingyun-cli init -y
```
- 打开配置文件。配置文件使用toml格式，生成的配置文件说明：
```
[auth]
# 平台access token, 应用设置获取
token = ""

[base]
# 应用名称, 可选, 标记作用, 应用设置获取
app_name = ""
# 应用token, 应用设置获取
app_token = ""
# sourcemap上传地址, 应用设置获取
beacon = ""
# 产品类型, 应用设置获取 
product_type = "mp"
```
- 在应用设置界面复制配置信息，粘贴到.tingyunclirc.toml文件，保存。
上传Source Map。

命令结构：
```
tingyun-cli release upload <版本> <上传文件或目录> --sourcemap
```
为了准确解析不同版本js文件的报错， source map文件必须上传到某个版本下(关于版本cli命令见下方完整命令列表)。此版本是用户项目的应用版本，每次js文件重新打包都需要重新更换版本上传。

示例：
```
tingyun-cli release upload V1.0.0 ./dist --sourcemap
```
上传dist目录下的sourcemap文件到V1.0.0版本。
设置应用版本。

为了准确关联JS错误版本，用户项目中需要在嵌码代码后加入monitor.setReleaseId。此值需要在每次发版时与上一步指定的版本保持一致。
```
monitor.setReleaseId('V1.0.0');
```
探针会获取monitor.setReleaseId的内容作为应用版本上传。

CLI命令

查看版本：

tingyun-cli -v

tingyun-cli init

--yes， -y 可以跳过问卷，生成一个模板配置文件：

tingyun-cli init -y

展示当前版本列表

tingyun-cli release list

删除版本

tingyun-cli release delete <release>

创建版本

tingyun-cli release new <release>

上传版本

tingyun-cli release upload <release> <files>... [flags]

Flags说明：

--sourcemap：按SourceMap形式处理上传文件，默认识别.map文件，并尝试解析.js中sourcemapping映射。

--no-overwrite：上传不覆盖同名文件，默认覆盖。

--config：指定配置文件路径，全局flags，对所有命令子命令都生效。

tingyun-cli release upload V1.0.0 ./dist --sourcemap --config /my/config/dir/.tingyunclirc

SourceMap