跳转至

在项目构建过程中上传 sourcemaps

我们目前提供了 webpack 插件,能够轻松的在 Web 项目构建的过程中,上传对应目录的 sourcemaps 文件。解决在繁杂的手动上传过程。 ! (目前支持 web 应用的上传)

准备工作

  1. 获取对应站点的 OpenApi 域名地址 (如何获取)
  2. 在观测云获取对应的 OpenApi所需的 API KEY获取方式)。
  3. 在观测云平台上获取 web 应用的applicationIdenvversion信息,如果没有应用,可以创建一个新应用
  4. 准备完毕

Webpack

安装 @cloudcare/webpack-plugin

 npm install @cloudcare/webpack-plugin --D

修改 webpack.config.js 文件的 plugins 选项

// ....
const { GuanceSourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')
module.exports = ({ mode }) => ({
  //.....
  devtool: 'hidden-source-map',
  plugins: [
    //.....
    new GuanceSourceMapUploadWebpackPlugin({
      applicationId: 'xxxxx', //  观测云应用 appid
      apiKey: 'xxxxxxxx', // open apikey
      server: 'https://console.guance-xxx.cn',
      filepaths: ['dist/'], // 需要搜索的目录,可以是文件或者文件目录
      logLevel: 'verbose', // 日志打印级别,非必填
      root: 'dist/', // 设置相对路径应计算的目录,非必填
      env: 'production', // 观测云 应用的 env,非必填
      version: '1.0.0', // 观测云应用的 version,非必填
    }),
  ],
})

Sourcemap WebpackPlugin 配置说明

interface Options {
  /**
   *
   * 要搜索 sourcemap 的文件/目录。
   * 所有与 “extensions 配置” 列表匹配但与“ignore 配置”不匹配的文件都将被搜索
   * sourcemap JSON 或 `//#sourceMappingURL=` 注释,以便找到生成的文件 + 源映射对,然后源映射将被上传。
   */
  filepaths: Array<string> | string

  /**
   * 观测云平台生成的openApi Key,生成方式参考(https://docs.guance.com/management/api-key/open-api/#_1)
   */
  apiKey: string

  /**
   * 观测云平台 OpenAPi 服务
   */
  server: string
  /**
   * 观测云 RUM 应用对应的 applicationId(必填)
   */
  applicationId: string
  /**
   * 观测云 RUM 应用对应的 version(非必填)
   */
  version?: string
  /**
   * 观测云 RUM 应用对应的 env(非必填)
   */
  env?: string

  /**
   * 寻找所有符合条件的文件列表,但是不上传文件,可用于调试
   */
  dryRun?: boolean

  /**
   * 上传后删除所有找到的源映射文件。
   */
  deleteAfterUpload?: boolean
  /**
   * 如果源映射无法通过其 sourceMappingURL 与生成的文件匹配,尝试通过本地磁盘上的文件名进行匹配
   */
  matchSourcemapsByFilename: ?boolean

  /**
   * 寻找目录下的文件后缀列表
   * 默认 [".js", ".map"].
   */
  extensions?: Array<string>

  /**
   * 需要忽略的文件列表
   */
  ignore?: Array<string>

  /**
   * 设置相对路径应计算的目录。sourcemaps 上传的相对路径应该要包含在 产生 error 的路径内,因此
   * 这个参数的意义在于控制上传的相对目录
   * 默认为 `process.cwd()`.
   */
  root?: string
  /**
   * 调试时候使用,产生的日志的等级
   */
  logLevel?: 'quiet' | 'normal' | 'verbose'
}

Sourcemap 在生产环境的是否可见

在生产环境中,出于安全考虑,我们通常不会保留 sourcemap 文件。这些文件允许开发者将压缩或编译后的代码映射回原始源代码,但若被公开,可能会暴露应用程序的内部逻辑,增加安全风险。

为了安全地处理 sourcemap,您可以在配置 GuanceSourceMapUploadWebpackPlugin 时启用 deleteAfterUpload: true 选项。这样,一旦 sourcemap 被上传到服务器,就会立即从本地文件系统中删除,确保它们不会在生产环境中遗留。

此外,通过设置 Webpack 的 devtool 为 "hidden-source-map",您可以生成 sourcemap 而不在 JavaScript 文件中包含任何指向它们的引用。这可以防止浏览器尝试下载和查看源代码。

如果启用了 "hidden-source-map",您还应该在 GuanceSourceMapUploadWebpackPlugin 插件中设置 matchSourcemapsByFilename: true。这个配置确保插件能够根据 JavaScript 文件的名称来识别并上传相应的 sourcemap 文件,即使它们在生成的代码中没有显式的引用。

通过这些措施,您可以在保持应用程序调试便利性的同时,有效保护源代码的安全。

 const { GuanceSourceMapUploadWebpackPlugin } = require('@cloudcare/webpack-plugin')
 = require('@cloudcare/webpack-plugin')

module.exports = {
  // Ensure that Webpack has been configured to output sourcemaps,
  // but without the `sourceMappingURL` references in buidl artifacts.
  devtool: 'hidden-source-map',
  // ...
  plugins: [
    // Enable our plugin to upload the sourcemaps once the build has completed.
    // This assumes NODE_ENV is how you distinguish production builds. If that
    // is not the case for you, you will have to tweak this logic.
    process.env.NODE_ENV === 'production'
      ? [
          new GuanceSourceMapUploadWebpackPlugin({
            ...
            deleteAfterUpload: true,
            matchSourcemapsByFilename: true,
          }),
        ]
      : [],
  ],
}

如何 DEBUG

如果在运行过程中,没有找到对应的 sourcemap,可以通过设置环境变量 DEBUG=guance:sourcemap-upload 或者配置 logLevel: verbose 运行 build 命令,查看具体运行日志

注意事项

node 版本 > 10.13

filepathsroot 配置注意事项:

  1. 在观测云控制台有一个错误的其中一行 at SVGGElement.<anonymous> @ http://localhost:8000/js/chunk-vendors.732b3b98.js:1:93427

  2. 引起错误产生的文件相对路径为 js/chunk-vendors.732b3b98.js

  3. 如果 js 文件在服务端的静态目录为 dist/js/*.js dist/js/*.js.map

  4. 插件配置 filepaths: ['dist']

  5. 如果在不配置 root 的情况下,默认上传到观测云服务端的 sourcemap 文件路径 dist/js/**.js.map

  6. 这种情况下,就会出现上传文件的目录路径产生错误的路径不匹配的情况,所以这时候应该添加配置 root:'dist/', 保证上传的目录路径为 js/**.js.map

文档评价

文档内容是否对您有帮助? ×