微信小程序 Source Map 的使用及一键解析 - WXOPEN Club

背景介绍

在微信小程序后台的错误日志里或项目自己收集的错误日志里，经常会出现一些如下格式的错误堆栈信息:

Cannot read property 'video' of undefined
TypeError: Cannot read property 'video' of undefined
at a.<anonymous> (https://usr/app-service.js:8534:329320)
at s (https://usr/app-service.js:8534:2420)
at Object.next (https://usr/app-service.js:8534:1715)
at https://usr/app-service.js:8534:1440
at s (https://usr/app-service.js:8534:1211)
at a.t.swiperChangeUpDown (https://usr/app-service.js:8534:328219)
at a.<anonymous> (https://usr/app-service.js:8534:327713)
at s (https://usr/app-service.js:8534:2420)
at Object.next (https://usr/app-service.js:8534:1715)

以错误堆栈信息里的第 3 行为例，其显示错误发生在app-service.js文件的8543行329320列，但在我们的微信小程序的产出里并不存在类似的app-service.js文件。

实际上，在微信开发者工具或 CI 工具上传小程序项目时，会将项目里的app.js、各个页面的js文件等所有的 JS 文件编译并打包成一个 JS 文件（每个分包会单独打包成一个 JS 文件），这个文件就是app-service.js。

尽管有打包后的 JS 文件的报错位置，但想要定位到微信小程序源码里哪里报错，却依然比较困难。

Source Map

微信小程序为了开发者能够根据打包后的 JS 错误位置定位到源码里的错误位置，提供了 Source Map 支持。在开发者工具里若是开启了“ES6 转 ES5”、“代码压缩”，在上传代码时会生成Source Map文件，方便定位错误位置。

小程序后台获取的 Source Map 压缩包解压后的结构如下：

├── __APP__
│   └── app-service.map.map
├── __FULL__
│   └── app-service.map.map
├── sub-package-A
│   └── app-service.map.map
├── sub-package-B
│   └── app-service.map.map
└── ...
    └── app-service.map.map

其中：

__APP__/app-service.map.map是小程序主包的 Source Map 文件
__FULL__/app-service.map.map是小程序主包 + 分包合并在一起的 Source Map 文件
其他的是各个分包单独的 Source Map 文件，比如sub-package-A/app-service.map.map是sub-package-A分包的 Source Map 文件

获取到 Source Map 文件并按照官方的 Source Map 使用方法编写代码进行解析后，可以将app-service.js里的错误位置还原到上传之前的小程序代码。

然而，我第一次获得的小程序源码位置仍然不是我实际开发时的文件位置。对比解析得到的文件名称发现，我们是使用了小程序第三方开发框架uni-app并使用Vue.js来开发微信小程序的，而uni-app在生产环境打包时会将Vue.js开发的源码编译为经过压缩混淆的小程序代码，因此我们通过 Source Map 解析出的源码位置其实是uni-app编译产出的小程序代码的位置，而不是使用Vue.js编写的源码位置。

幸运的是，微信小程序针对这种“使用外部的编译脚本对源文件进行处理”的情况，也提供了解决方案，只需我们将第三方开发框架的源码在编译为小程序代码时生成的 Source Map 文件放置在小程序代码文件的相同目录下，开发者工具会读取、解析 Source Map 文件，并基于该 Source Map 文件在打包上传时生成最终的 Source Map 文件。

使用小程序第三方开发框架编译后产出的小程序代码目录：

├── pages
|   ├── index.js
|   ├── index.json
|   ├── index.wxml
|   ├── index.wxss
|   └── index.js.map
├── app.js
├── app.js.map

经过这样的方式产生的 Source Map 文件，就能将app-service.js里的错误位置映射到第三方开发框架的源码位置上。以下我将简单地描述如何配置项目来生成 Source Map 文件。

生成 Source Map

对于未使用小程序第三方框架而是采用原生的微信小程序语法开发的项目来说，只需要在project.config.json里配置开启“ES6 转 ES5”、“代码压缩”，这样在上传体验版时就会生成 Source Map 文件。

project.config.json里相关配置如下：

{
  "description": "小程序项目配置文件",
  "setting": {
    "es6": true,
    "minified": true,
    // ...
  }
}

针对使用了小程序第三方框架的项目，除了以上的project.config.json配置，还要配置第三方框架在生产环境打包时生成初始的 Source Map 文件。

以uni-app开发的项目来说，配置 Webpack 在生产环境打包时生成 Source Map 文件，并将该 Source Map 文件放置在与原先的 JS 文件同一目录下。

// vue.config.js
module.exports = {
    // ...
    configureWebpack: config => {
        if (process.env.NODE_ENV === 'production') {
            config.devtool = 'source-map';
            config.output.sourceMapFilename = '../' + process.env.UNI_PLATFORM + '/[name].js.map'
        }
    },
    // ...
}

获取 Source Map

目前有很多种方式获取 Source Map 文件：

若是通过微信开发者工具上传小程序代码，在上传完成后可以下载 Source Map 压缩包
若是通过CI 工具上传，可以在上传完成后调用ci.getDevSourceMap方法获取 Source Map 压缩包
此外，针对线上版小程序，可在“微信小程序后台 --> 开发管理 --> 错误日志 --> 错误内容”里下载

解析 Source Map

目前微信小程序官方主要提供了两种解析 Source Map 的方式。

方式一：自行编写代码进行解析。

import fs = require('fs')
import { SourceMapConsumer } from 'source-map'

async function originalPositionFor(line, column) {
  const sourceMapFilePath = 'Source Map 文件在硬盘里的位置'
  const sourceMapConsumer = await new SourceMapConsumer(JSON.parse(fs.readFileSync(sourceMapFilePath, 'utf8')))

  return  sourceMapConsumer.originalPositionFor({
      line,
      column,
   })
}

originalPositionFor(出错的行，出错的列)