Source Map
Source Map是一个存储源代码与编译代码对应位置映射的信息文件，便于开发人员定位上述代码错误。实际上，它就是一个JSON键值对，利用VLQ编码与特定的规则存储位置信息。简而言之，可以理解为Source Map在处理前的代码和处理后的代码之间搭建了一座桥梁。
对于前端应用来说，JS错误的发生直接影响前端应用的质量，因此对于JS错误的定位及诊断显得尤为重要。基调听云提供了Source Map上传来还原代码真正的错误位置，还原JS错误现场。这样使得开发者能够迅速定位出错的源代码位置以及相应的代码块。
Source Map上传支持两种方式：CLI和Webpack插件。
CLI使用说明
Tingyun CLI是一个CLI程序，是上传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 = "web" -
在应用设置>SourceMap页面复制配置信息， 粘贴到
.tingyunclirc.toml文件， 然后保存。
-
-
上传Source Map。
命令结构：
tingyun-cli release upload <版本> <上传文件或目录> --sourcemap为了准确解析不同版本JS文件的报错， Source Map文件必须上传到某个
版本下(关于版本CLI命令见下方完整命令列表)。此版本是用户项目的应用版本， 每次JS文件重新打包都需要重新更换版本上传。示例：
tingyun-cli release upload V1.0.0 ./dist --sourcemap上传dist目录下的Source Map文件到V1.0.0版本。
-
设置应用版本。
为了准确关联JS错误版本， 用户项目中需要在页面全局设置变量
TINGYUN_RELEASE， 变量类型为对象，属性id标识版本名称。此值需要在每次发版时与上一步指定的版本保持一致。window.TINGYUN_RELEASE = {
id: 'V1.0.0'
}探针会获取TINGYUN_RELEASE的id作为应用版本上传。
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：按Source Map形式处理上传文件， 默认识别.map文件，并尝试解析.js中sourcemapping映射。
--no-overwrite：上传不覆盖同名文件， 默认覆盖。
--config：指定配置文件路径， 全局flags，对所有命令子命令都生效。
示例：
tingyun-cli release upload V1.0.0 ./dist --sourcemap --config /my/config/dir/.tingyunclirc
Webpack插件使用说明
Webpack插件简化了CLI上传Source Map流程， 可以更好的集成到项目的版本发布中。
使用
-
安装。
进入前端项目的根目录，通过npm安装：
npm install @tingyun-common/source-map-webpack-plugin --save-dev -
在Webpack配置中加入SourceMap插件。
// 导入sourcemap插件
const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');
module.exports = {
// 建议只在生产模式使用
mode: 'production',
//...
plugins: [
new TingyunSourceMapWebpackPlugin({
// 指定打包生成的文件目录, 根据实际情况填写, 例如: './dist'
include: '<上传目录或文件>',
// 设置上传sourcemap的版本号, 如果不设置, 插件会自动生成, 例如; V1.0.0
release: '<版本号>'
// 指定上传的配置信息。如果当前项目目录存在tingyun-cli配置文件.tingyunclirc 或 .tingyunclirc.toml可以不写
beacon: '<上传地址>',
appToken: '<app_token>',
token: '<access_token>',
productType: '<产品类型>', //web或mp
}),
// ...
// 其他插件
],
};- **Webpack插件在每次执行时都会创建版本并上传Source Map， 建议只在生产环境打包时执行插件， 防止 大量不必要的版本上传！**可参考Webpack官方文档：生产打包的最佳实践。
- 如果当前目录存在tingyun-cli配置文件
.tingyunclirc或.tingyunclirc.toml， Webpack插件配置中可以不设置上传信息。
Demo项目
配置示例
下面列举了流行的脚手架项目的使用方式。根本目的是在Webpack配置中加入基调听云Source Map插件， 如果下列参考配置没有覆盖你的使用场景， 请根据实际情况配置。
使用前首先确保已经安装Webpack插件：
npm install @tingyun-common/source-map-webpack-plugin --save-dev
然后参考下列配置操作。
create-react-app
建议使用react-app-rewired来增加Webpack插件。如果你的项目中已经使用eject脚本暴露了Webpack配置， 请自行分析项目配置添加Webpack插件。
示例使用的版本:
create-react-app 4.0.3
-
安装
react-app-rewired。npm install react-app-rewired --save-dev -
修改
package.json脚本的script部分， 使用react-app-rewired替换react-scripts。"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-scripts eject"
}, -
在项目根目录添加或修改
config-overrides.js。const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');
module.exports = {
webpack: (config) => {
if (process.env.NODE_ENV === "production") {
if (!config.plugins) {
config.plugins = [];
}
// 生产环境加入webpack插件
config.plugins.push(
new TingyunSourceMapWebpackPlugin({
include: "./build",
// 其他配置
})
)
}
return config;
},
} -
打包。
npm run build
执行打包命令后， 控制台会打印插件输出的上传信息。
vue-cli
示例使用的版本：
@vue/cli 4.5.13
-
创建或修改
vue.config.js文件。const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');
module.exports = {
configureWebpack: (config) => {
if (process.env.NODE_ENV === "production") {
// 生产环境加入webpack插件
config.plugins.push(
new TingyunSourceMapWebpackPlugin({
include: "./dist",
// 其他配置
})
)
}
},
}; -
打包。
打包命令请根据实际情况填写， 默认是
build。npm run build
执行打包命令后， 控制台会打印插件输出的上传信息。
angular-cli
示例使用的版本：
Angular CLI: 12.0.4
-
进入项目目录安装
@angular-builders/custom-webpack。npm install @angular-builders/custom-webpack --save-dev -
修改
angular.json。"projects": {
...
// [project]是实际项目名
"[project]": {
...
"architect": {
...
// 修改对应的ng命令, 此处以修改build为例
"build": {
// 修改默认builder
// "builder": "@angular-devkit/build-angular:browser",
"builder": "@angular-builders/custom-webpack:browser"
"options": {
// 增加自定义webpack文件配置
"customWebpackConfig": {
// webpack配置文件名称, 名称自定义
"path": "./webpack.config.js"
}
},
"configurations": {
"production": {
// 如果没有开启sourcemap生成, 设置开启sourcemap
"sourceMap": true
}
} -
修改/创建Webpack配置文件。
此处配置文件的生成位置取决于angular.json中配置的路径。
webpack.config.js
const TingyunSourceMapWebpackPlugin = require('@tingyun-common/source-map-webpack-plugin');
module.exports = (config, options) => {
if (config.mode === "production") {
if (!config.plugins) {
config.plugins = [];
}
config.plugins.push(
new TingyunSourceMapWebpackPlugin({
include: "./dist",
// 上传配置可以在此处指定或者创建cli配置文件
})
)
}
return config;
}; -
打包。
npm run build
执行打包命令后，控制台会打印插件输出的上传信息。