Source Map

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

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

Source Map上传支持两种方式：CLI和Webpack插件。

CLI使用说明

Tingyun CLI是一个CLI程序，是上传Source Map的主要方式。

安装

npm安装

当前工作目录安装：

  1. 进入前端工程目录，安装CLI包。

    npm install @tingyun-common/cli

  2. 验证安装成功。

    ./node_modules/.bin/tingyun-cli -v

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

全局安装：

  1. 安装。

    npm install -g @tingyun-common/cli --unsafe-perm

    需要确保有权限访问全局的node_modules目录，如果在Linux、Mac环境遇到权限问题，建议使用root安装。

    sudo npm install -g @tingyun-common/cli --unsafe-perm

  2. 验证安装成功。

    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程序，需要在终端中使用。

使用

  1. 初始化。

    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文件， 然后保存。

  2. 上传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版本。

  3. 设置应用版本。

    为了准确关联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流程， 可以更好的集成到项目的版本发布中。

使用

  1. 安装。

    进入前端项目的根目录，通过npm安装：

    npm install @tingyun-common/source-map-webpack-plugin --save-dev

  2. 在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

  1. 安装react-app-rewired。

    npm install react-app-rewired --save-dev

  2. 修改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"
},

  3. 在项目根目录添加或修改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;
    },
  }

  4. 打包。

    npm run build

执行打包命令后， 控制台会打印插件输出的上传信息。

vue-cli

示例使用的版本：

@vue/cli 4.5.13

  1. 创建或修改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",
            // 其他配置
          })
      )
    }
  },
};

  2. 打包。

    打包命令请根据实际情况填写， 默认是build。

    npm run build

执行打包命令后， 控制台会打印插件输出的上传信息。

angular-cli

示例使用的版本：

Angular CLI: 12.0.4

  1. 进入项目目录安装@angular-builders/custom-webpack。

    npm install @angular-builders/custom-webpack --save-dev

  2. 修改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
          }
        }

  3. 修改/创建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;
};

  4. 打包。

npm run build

执行打包命令后，控制台会打印插件输出的上传信息。

© 2007-2023 北京基调网络股份有限公司 all right reserved，powered by Gitbook本文档更新于： 2023-12-18 16:44

results matching ""

    No results matching ""