setup-browser-sdk-sourcemaps

使用构建插件设置 Datadog 源码映射上传

使用 Datadog 构建插件，在前端项目中添加构建时源码映射上传。源码映射会在构建过程中上传，因此每次部署都会向 RUM 和 Error Tracking 提供未压缩的堆栈跟踪信息。Git 元数据会自动附加，从而将错误关联到源文件。

请按顺序完成步骤 1–7。

开始任何工作之前： 创建恰好 7 个待办事项，分别对应以下每个步骤。创建完全部 7 个待办事项后，才能开始实施。不得压缩或合并步骤。

切勿编造值。 三个字段（service、releaseVersion、minifiedPathPrefix）必须与应用的实际部署方式一致。如果无法从代码仓库中读取某个值，请停止并询问用户。不要填写占位符、TODO 或猜测的主机名。

范围

范围内：使用 esbuild、Rollup、Rspack、Vite 或 webpack 构建的项目，包括在自身配置文件中直接提供上述任一工具的元框架（例如，Remix/React Router v7+ 框架模式、SvelteKit，以及通过 vite.config.ts/nuxt.config.ts 的 vite: 配置项使用 Vite 的 Nuxt）。如果下面步骤 1 的配置文件搜索找到了真实的打包工具配置，那么其上层的元框架不会改变任何事项——按常规方式将插件接入该配置文件。

范围外：Next.js 和 Turbopack。与上述元框架不同，Next.js 不提供可供插件接入的纯 webpack/Turbopack 配置接口，也完全没有 Next.js 或 Turbopack 集成。对于这些项目，请改用 postbuild 脚本中的 datadog-ci sourcemaps upload CLI——不要尝试通过 next.config.js 接入 webpack 插件。

如果项目使用了此处未列出的其他元框架，并且步骤 1 未找到可编辑的纯打包工具配置文件，请停止并询问，不要猜测是否受支持。

步骤 1：检测打包工具

搜索打包工具配置文件：

find . -maxdepth 1 \( -name "vite.config.*" -o -name "rollup.config.*" -o -name "webpack.config.*" -o -name "rspack.config.*" -o -name "esbuild.config.*" \) 2>/dev/null
grep -l -E "\"(vite|rollup|webpack|@rspack/core|esbuild)\"" package.json

请使用 find，不要直接对这些 glob 模式使用 ls——在 zsh 中，如果多个 glob 模式中的任意一个未匹配到文件，ls 调用就会因 no matches found 而中止，即使追加了 2>/dev/null 也是如此，因为错误发生在 shell 执行 ls 之前的单词展开阶段。find 会在内部进行模式匹配，因此在 bash 和 zsh 中行为一致；如果不存在打包工具配置文件，它会正确返回空结果，而不会报错。

根据结果进行映射：

配置文件	打包工具	要安装的包	命名导出
vite.config.{js,ts,mjs}	Vite	@datadog/vite-plugin	datadogVitePlugin
webpack.config.{js,ts,mjs}	webpack	@datadog/webpack-plugin	datadogWebpackPlugin
rollup.config.{js,ts,mjs}	Rollup	@datadog/rollup-plugin	datadogRollupPlugin
rspack.config.{js,ts,mjs}	Rspack	@datadog/rspack-plugin	datadogRspackPlugin
esbuild 构建脚本	esbuild	@datadog/esbuild-plugin	datadogEsbuildPlugin

支持的打包工具版本：

打包工具	支持范围
esbuild	任意版本
Rollup	>= 3 < 5
Rspack	1.x 或 2.x
Vite	>= 5 <= 8
webpack	>= 5 < 6

出现以下情况时，请停止并询问用户： 未找到打包工具配置文件、找到多个配置文件（单体仓库——询问要为哪个应用添加监控）、检测到 Next.js 或 Turbopack（超出范围，见上文），或者打包工具版本不在支持范围内。

第 2 步：收集三个必需值

缺少这三个值，插件将无法构建。请从仓库中读取；无法读取的值请向用户询问。

service — 必须与传递给 datadogRum.init() 的 service 相同。Datadog 会根据此值将上传的 sourcemap 与传入的错误相匹配。如果不匹配，sourcemap 虽然会成功上传，却永远不会被使用。

grep -rn "datadogRum.init" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 15

如果在任何位置都找不到 datadogRum.init() 调用，请停止：此技能只会为现有的 RUM 配置添加 sourcemap 上传，不会自行配置 RUM。请告知用户需要先设置 Browser RUM，然后重新运行此技能。

如果 datadogRum.init() 没有 service，请停止并告知用户：没有此值就无法匹配 sourcemap，必须先将其添加到 RUM 初始化配置中。

releaseVersion — 必须与传递给 datadogRum.init() 的 version 相同。通常是 git 提交 SHA、发布标签或 CI 构建 ID。可以在此设置，也可以在顶层通过 metadata.version 设置一次。如果两者都已设置且值不同，构建将失败，并显示 sourcemaps.releaseVersion must match metadata.version when both are configured。

minifiedPathPrefix — 构建后的 JS 所在的 URL 前缀。必须是完整 URL 或以 / 开头，否则构建将失败，并显示 sourcemaps.minifiedPathPrefix must be a valid URL or start with '/'。

示例：如果 dist/main.js 的访问地址为 https://example.com/static/main.js，那么 minifiedPathPrefix 就是 https://example.com/static/ 或 /static/。如果 JS 从服务器根目录提供，/ 也是有效值。

这是最容易设置错误的字段，而且无法仅凭打包器配置推断出来。询问用户之前，请先检查仓库，了解项目实际的部署方式：

1. 首先检查打包器自身的 base/publicPath/baseURL 配置——如果已设置，就能直接确定答案。
2. 否则，检查部署/CI 配置，确认实际的部署命令和目标目录： .github/workflows/*.yml、.gitlab-ci.yml、vercel.json、netlify.toml、wrangler.toml、 Dockerfile。如果部署步骤直接部署打包器的输出目录（例如 pages deploy ./dist、netlify deploy --dir=build），前缀就是该目录根目录的访问 URL（如果部署在服务器根目录，则为 /）。不要添加资源子目录，例如 Vite 的 assets/：插件会在每个文件路径前追加输出目录中的相对路径，因此 /assets/ 会上传 /assets/assets/index-*.js。
3. 检查是否存在可能覆盖上一步答案的路径重写配置：Cloudflare 的 _routes.json / _redirects、Netlify 的 _redirects、vercel.json 中的 Vercel rewrites。如果存在，请根据重写规则重新推导前缀，而不是使用原始构建输出路径。
4. 如果以上方法都无法确定答案——仓库中没有已提交的部署配置，或自定义域名/CDN 仅在托管控制面板中配置——请停止并询问用户。给出具体的检查方法，不要只让用户自行查找：请在实际运行的网站上打开浏览器开发者工具，进入 Network 标签页，重新加载页面，然后找到主 JS bundle 实际加载的 URL。

即使检查了上述所有内容，也不要填写占位符、TODO 或猜测的主机名。

第 3 步：安装插件

npm install --save-dev @datadog/<bundler>-plugin

使用项目的包管理器：yarn add -D、pnpm add -D 或 bun add -d。

步骤 4：让打包器生成 sourcemap

这是最常见的静默失败。 插件会上传构建生成的所有 .map 文件。如果没有配置打包器生成这些文件，它就找不到任何文件，只会记录一条 No sourcemaps to upload 警告，而构建仍会成功。Datadog 中不会显示任何内容，也不会有错误说明原因。

这些是打包器原生设置，不是插件选项。Datadog 构建插件不会设置这些选项，也不会说明这些设置。

打包器	设置
webpack	devtool: 'source-map'
Rspack	devtool: 'source-map'
Vite	build.sourcemap: true
Rollup	output.sourcemap: true
esbuild	sourcemap: true

如果缺少此设置，请添加。如果项目有意在生产环境中禁用 sourcemap，请暂停并告知用户——公开提供隐藏的 sourcemap 确实有风险，而且插件上传后不会删除文件，因此除非部署流程会剥离 .map 文件，否则它们仍会随应用发布。

步骤 5：在配置中接入插件

将插件注册为 plugins 数组中的第一个插件——插件自己的 README 建议在所有五种打包器中都这样做，以确保完整的构建报告。

不要将 API key 写入配置文件。插件会从环境中读取 DATADOG_API_KEY（或 DD_API_KEY），且环境变量的优先级高于配置值。不在配置文件中填写，可以避免凭据进入版本控制。

Vite（vite.config.js）：

import { defineConfig } from 'vite';
import { datadogVitePlugin } from '@datadog/vite-plugin';

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    datadogVitePlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
});

webpack（webpack.config.js）：

const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
  devtool: 'source-map',
  plugins: [
    datadogWebpackPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
};

Rspack（rspack.config.js）——与 webpack 相同，但使用来自 @datadog/rspack-plugin 的 datadogRspackPlugin。

Rollup（rollup.config.js）：

import { datadogRollupPlugin } from '@datadog/rollup-plugin';

export default {
  output: { sourcemap: true },
  plugins: [
    datadogRollupPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
};

esbuild（构建脚本）：

const { datadogEsbuildPlugin } = require('@datadog/esbuild-plugin');

require('esbuild').build({
  sourcemap: true,
  plugins: [
    datadogEsbuildPlugin({
      errorTracking: {
        sourcemaps: {
          service: 'my-service',
          releaseVersion: process.env.GIT_COMMIT_SHA,
          minifiedPathPrefix: '/static/',
        },
      },
    }),
  ],
});

将所有值替换为步骤 2 中收集的值。不要保留 'my-service' 或 '/static/'。

仅当用户提出要求时，才设置以下可选子选项：

选项	默认值	作用
dryRun	false	文档说明此选项会执行除上传之外的所有操作——请勿依赖它来确保安全，参见步骤 7
bailOnError	false	在首次上传错误时使构建失败
maxConcurrency	20	并发上传数

步骤 6：在构建环境中设置凭据

上传需要 API key。不需要应用程序 key。

变量	用途
DATADOG_API_KEY 或 DD_API_KEY	必需。缺少此项时，上传会失败并显示 No authentication token provided。
DATADOG_SITE 或 DD_SITE	非 US1 组织必需。默认值为 datadoghq.com。请根据实际情况使用 datadoghq.eu、us3.datadoghq.com、us5.datadoghq.com、ap1.datadoghq.com、ap2.datadoghq.com 或 ddog-gov.com。

将这些变量设置为 CI／构建密钥。切勿将 key 写入已提交的文件。

询问用户之前，先检查仓库中实际执行构建命令（build 脚本）的配置——密钥需要注入到执行构建的环境中，该环境不一定与最终的托管目标相同。GitHub Actions 工作流可能会运行构建，然后在单独的步骤中将输出部署到 Cloudflare Pages、Netlify、Vercel 或 S3；这种情况下，密钥应添加到工作流，而不是托管平台。

在仓库中发现的线索	实际运行构建的位置	添加密钥的位置
.github/workflows/*.yml 中有构建／安装步骤	GitHub Actions	仓库 Settings → Secrets and variables → Actions
.gitlab-ci.yml	GitLab CI	Settings → CI/CD → Variables
vercel.json，或没有 CI 文件且通过 Vercel 自身的构建流程部署	Vercel	Project Settings → Environment Variables
netlify.toml，或没有 CI 文件且通过 Netlify 自身的构建流程部署	Netlify	Site Settings → Environment variables
有 Dockerfile／docker-compose.yml，且没有 CI 工作流调用它	Docker，具体取决于镜像的构建位置	取决于部署流水线——请询问用户

请向用户确认检测到的提供商，不要自行假设——仓库中可能残留已不再使用的提供商配置。如果没有匹配项，请暂停并询问构建在哪里运行。

步骤 7：验证

Git 元数据会自动附加。enableGit 是一个顶层选项，默认值为 true，因此无需启用任何内容——只需避免破坏现有配置。除非步骤 7 出现下方所述的特定错误，否则不要设置此选项。

不要依赖 dryRun: true 来安全测试。 文档称它会“执行除上传之外的所有操作”，但这并不可靠——至少有一个已正式发布的插件版本会完全忽略此标志，仍然执行实时的、经过身份验证的上传。出于安全考虑，应将 dryRun 视为未经验证；在已安装的版本中，它可能会也可能不会跳过网络调用。

要测试发现流程且确保不会上传任何内容，唯一有保证的办法是：确保构建运行环境中的任何位置都未设置 DATADOG_API_KEY/DD_API_KEY——务必明确检查，因其他本地工具（例如个人的 datadog-ci 配置）遗留下来的密钥也会被静默读取。无法获取密钥时，无论 dryRun 如何设置，插件都无法通过身份验证。然后运行正常的生产构建（无需 dryRun）：

• 如果日志中出现 No sourcemaps to upload，则步骤 4 不正确——插件没有找到 .map 文件。此检查会在本地、任何网络调用之前执行，不受凭据影响。
• 如果没有出现这条日志——你可能会看到 Git 元数据警告，随后构建因 No authentication token provided 而失败——这就确认步骤 4 和 5 正确。插件找到了 sourcemap；它只是因为无法获取密钥而停止，这正是在未设置密钥时预期且安全的结果。

只有通过上述检查后，才能继续测试真实上传流程，而且必须有意为之——这是一个会产生实际影响的操作，不应随意执行。请明确向用户确认将使用哪个密钥：

• 如果他们想在本地验证真实上传流程，需要在此测试所用的 shell 中导出自己的有效 DATADOG_API_KEY（若非 US1，还需导出 DATADOG_SITE）。
• 如果他们的 shell 中已经为其他工具设置了密钥，此处也会使用该密钥——继续之前请确认这确实是他们的本意，因为上传会立即进行，目标是该密钥所属的组织，而不是沙盒或仅限 CI 的目标环境。

**如果构建失败并显示 Error: No git remotes available：**构建环境中没有 Git 远程仓库，这在浅克隆的 CI 和容器构建中很常见。可按优先顺序选择以下两种办法：在构建环境中提供 Git 远程仓库（更好——这样可以保留错误与源码的关联），或者在插件配置顶层设置 enableGit: false，以彻底禁用 Git 信息收集。

datadogWebpackPlugin({
  enableGit: false,
  errorTracking: { sourcemaps: { /* ... */ } },
})

端到端确认：在已部署的应用中触发一个错误，并检查 Datadog Error Tracking 中的堆栈跟踪是否未经过压缩。

常见错误

• service 或 releaseVersion 与 datadogRum.init() 中的值不一致。上传成功，但 sourcemap 永远不会与任何错误匹配。这种情况不会显示任何提示。
• 忘记在步骤 4 中设置打包工具的 sourcemap 选项。构建会通过，但只会出现警告。
• 根据输出目录而不是实际提供资源的 URL 来猜测 minifiedPathPrefix。dist/ 不是 URL 前缀。
• 将 apiKey 放进已提交的配置文件，而不是构建环境中。
• 因为工单要求“启用 Git”就设置 enableGit: true。它本来就是默认值；设置它不会有任何改变。
• 将 releaseVersion 和 metadata.version 设为不同的值，这会导致构建失败。
• 尝试在 Next.js 中使用构建插件。它没有 Next.js 集成。

验证清单

• 已检测到 Bundler，且版本在支持范围内
• 已将插件包安装为开发依赖
• 已配置 Bundler 生成 sourcemap（步骤 4 的表格）
• 插件已在 plugins 数组中优先注册
• service 与 datadogRum.init() 的 service 一致
• releaseVersion 与 datadogRum.init() 的 version 一致
• minifiedPathPrefix 是完整 URL 或以 / 开头，并与 JS 的实际托管位置一致
• 已提交的文件中没有 API 密钥
• 已在构建环境中设置 DATADOG_API_KEY（如果不是 US1，还需设置 DATADOG_SITE）
• 在无法访问 API 密钥的情况下构建时，会报告找到 sourcemap（到达 No authentication token provided），而不是 No sourcemaps to upload——不要使用 dryRun 进行此检查， 请参阅步骤 7
• 实际构建成功，且部署后出现的错误显示未压缩的堆栈跟踪