如何在作为依赖的NPM包中使用Rollbar并配置Source Maps？

我之前开发公用NPM包时也碰到过完全一样的Rollbar错误追踪问题！折腾了好一阵子才理顺，分享下我的解决方案，应该能帮到你：

核心问题分析 #

你的包作为依赖被其他项目引入后，编译后的代码是压缩/混淆过的，Rollbar需要Source Maps来映射回原始源码才能展示错误详情。控制台能显示错误是因为浏览器自动加载了本地的Source Maps，但Rollbar服务器端没有对应的映射文件，所以无法解析。

具体配置步骤 #

1. 打包时生成标准的独立Source Maps #

不管你用Rollup还是Webpack，都要确保生成独立的.map文件（不要用inline或eval类型的Source Maps，Rollbar对这类支持不友好）：

Rollup配置示例：

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/my-package.cjs.js',
      format: 'cjs',
      sourcemap: true // 生成单独的Source Map文件
    },
    {
      file: 'dist/my-package.esm.js',
      format: 'esm',
      sourcemap: true
    }
  ]
}

Webpack配置示例：

module.exports = {
  devtool: 'source-map', // 必须用source-map类型，生成独立的.map文件
  output: {
    filename: 'my-package.js',
    sourceMapFilename: 'my-package.js.map' // 指定输出的Source Map文件名
  }
}

2. 上传Source Maps到Rollbar服务器 #

Rollbar需要拿到你的Source Map文件才能做映射，推荐用打包插件自动上传：

Webpack用户：使用rollbar-sourcemap-webpack-plugin

先安装插件：

npm install rollbar-sourcemap-webpack-plugin --save-dev

然后在Webpack配置中添加：

const RollbarSourceMapPlugin = require('rollbar-sourcemap-webpack-plugin');
const pkg = require('./package.json');

module.exports = {
  // ...其他配置
  plugins: [
    new RollbarSourceMapPlugin({
      accessToken: '你的Rollbar服务器端Token',
      version: pkg.version, // 用package.json的版本号，确保和发布的包版本一致
      publicPath: 'https://unpkg.com/你的包名@' + pkg.version + '/dist/' // 包的CDN路径或用户引入的资源路径
    })
  ]
}

Rollup用户：使用rollup-plugin-rollbar-sourcemaps

安装插件：

npm install rollup-plugin-rollbar-sourcemaps --save-dev

Rollup配置中添加：

import rollbarSourcemaps from 'rollup-plugin-rollbar-sourcemaps';
import pkg from './package.json';

export default {
  // ...其他配置
  plugins: [
    rollbarSourcemaps({
      accessToken: '你的Rollbar服务器端Token',
      version: pkg.version,
      publicPath: 'https://unpkg.com/你的包名@' + pkg.version + '/dist/'
    })
  ]
}

3. 正确初始化Rollbar实例 #

在你的NPM包中初始化Rollbar时，必须指定codeVersion和root路径，帮Rollbar定位源码：

import Rollbar from 'rollbar';
import pkg from '../package.json';

const rollbar = new Rollbar({
  accessToken: '你的Rollbar客户端Token',
  environment: process.env.NODE_ENV || 'production',
  codeVersion: pkg.version, // 和上传Source Maps时的版本号一致
  captureUncaught: true,
  captureUnhandledRejections: true,
  root: 'https://unpkg.com/你的包名@' + pkg.version + '/src/' // 原始源码的根路径
});

export default rollbar;

验证方法 #

1. 打包你的包，发布到NPM或用npm link本地关联到示例项目
2. 在示例项目中触发一个明确的错误（比如调用包中抛出错误的函数）
3. 打开Rollbar后台查看错误详情，检查是否显示原始的文件名、行号和代码片段
4. 可以去Rollbar项目的「设置 → Source Maps」页面，确认对应的版本和Source Map文件已成功上传

额外排查点 #

• 确保.map文件和编译后的包文件一起发布到NPM，不要在.gitignore中忽略它们
• 如果用户是本地安装你的包而非CDN，确保Rollbar初始化时sourceMapEnabled: true，且用户项目没有禁用Source Maps
• 查看Rollbar错误事件的「Raw Data」标签，检查source_map字段是否有加载失败的提示（比如404），这说明Rollbar找不到你的Source Map文件

内容的提问来源于stack exchange，提问作者Adriana Pineda