故障排除

如果您已经配置了 Sentry SDK，但它没有向 Sentry 发送任何数据：

• 检查您是否已配置 DSN 并将其传递给 Sentry.init() 中的 dsn 选项。

  如果您使用环境变量来传递 DSN，请确保这些环境变量在所有相关环境中都已设置。此外，如果您在框架内使用环境变量，请检查框架是否会将环境变量包含在您的包中。通常这意味着您需要为环境变量添加框架定义的特殊前缀（例如，在 Next.js 中使用 NEXT_PUBLIC_，在 Nuxt 中使用 NUXT_，在 Vite 项目中使用 VITE_，在 Create React App 中使用 REACT_APP_ 等）。

• 检查您是否已禁用所有广告拦截器。

• 在 Sentry.init() 选项中设置 debug: true，并在启动应用程序时观察控制台输出。SDK 可能会告诉您为什么它没有发送任何数据。

• 检查 Sentry 的 统计信息 和 订阅 页面。您可能已经用完了配额。

如果您将 Sentry SDK 升级到一个新的主要版本，可能会遇到需要您进行调整的破坏性更改。 请查阅我们的 迁移指南，以了解所有需要知道的内容，确保您可以顺利使用最新的 Sentry 功能。

您可以查看事件的 JSON 负载，以了解 Sentry 如何在事件中存储附加数据。数据结构可能与描述不完全一致。

更多详情，请参阅 关于事件负载的完整文档。

maxValueLength 的默认值为 250，但如果您的消息更长，您可以根据需要调整此值。请注意，并不是每个单独的值都会受此选项的影响。

当使用 ESM（ECMAScript 模块）时，默认情况下所有包都会通过 import-in-the-middle 在底层进行包装。import-in-the-middle 与某些包存在兼容性问题，在这些情况下可能会抛出错误。

更多详情，请参阅 ESM 故障排除 instrumentation 部分。

当您包含并配置 Sentry 时，我们的 JavaScript SDK 会自动附加全局处理器以 捕获 未捕获的异常和未处理的 Promise 拒绝。您可以通过将 onunhandledrejection 选项设置为 false 来禁用此默认行为，并手动挂钩每个事件处理器，然后直接调用 Sentry.captureException 或 Sentry.captureMessage。

如果您使用第三方库来实现 Promise，可能还需要管理您的配置。此外，请记住，浏览器通常会实施安全措施，这些措施可能会在从不同源提供脚本文件时阻止错误报告。

如果您看到带有消息“非 Error 异常（或 Promise 拒绝）捕获，键为：x, y, z。”的错误，这发生在以下情况：a) 使用普通对象调用 Sentry.captureException()；b) 抛出普通对象；c) 使用普通对象拒绝 Promise。

您可以在“附加数据”部分的 __serialized__ 入口中查看相关非 Error 对象的内容。

为了更好地了解这些错误事件，我们建议根据 __serialized__ 数据的内容，找到将普通对象传递或抛给 Sentry 的位置，并将普通对象转换为 Error 对象。

如果您正在使用 Vite 打包工具 和 Sentry NPM 包，并且遇到以下错误：

Error: Could not resolve './{}.js' from node_modules/@sentry/utils/esm/index.js

这可能是由于您的 Vite 配置中的 define 选项替换了 Sentry SDK 使用的某些变量（如 global），从而导致构建错误。Vite 建议仅将 define 用于常量，而不应将 process 或 global 放入选项中。要修复此构建错误，请删除或更新您的 define 选项，如下所示：

export default defineConfig({
   build: {
     sourcemap: true
   },
-  define: {
-    global: {}
-  },
   plugins: [react()]
})

如果您在使用任何 JavaScript SDK 时遇到构建错误，提示类似于“找不到模块 diagnostics_channel”的信息，请尝试配置您的构建工具以外部化或忽略 diagnostics_channel 模块。 Sentry Node.js SDK 使用这个内置模块来instrument Node.js 的 fetch 请求。 某些较旧版本的 Node.js 不包含 diagnostics_channel API，这可能导致在打包代码时出现构建错误。

大多数打包工具都有选项可以外部化特定模块（如 diagnostics_channel）：

• Webpack 中的 externals
• Vite 中的 external
• esbuild 中的 external
• Rollup 中的 external

如果您使用了自定义的 Webpack 插件，该插件使用 Terser 或其他压缩工具，您可能会遇到由于已知的 Webpack 错误导致的构建错误。此问题已在 Webpack 版本 5.85.1 及以上版本中修复。

有关此问题的更多详情，请参阅 webpack/terser-plugin 构建错误。

当使用 pnpm 时，您可能会遇到与无法外部化的包相关的错误，特别是像 import-in-the-middle 和 require-in-the-middle 这样的包。这些错误通常是由于 pnpm 的严格依赖管理及其提升行为引起的。

虽然将这些包添加为直接依赖项可能会消除警告信息，但这通常并不能解决潜在的功能问题。要彻底解决问题，您可以尝试以下方法：

1. 检查依赖树：确保所有相关依赖项都正确安装，并且没有版本冲突。
2. 调整 pnpm 配置：根据需要调整 pnpm 的配置文件（如 .npmrc 或 pnpm-workspace.yaml），以允许特定包的正确解析。
3. 使用别名：在 package.json 中使用 overrides 字段来覆盖某些包的版本，确保兼容性。

更多详情，请参阅 pnpm 官方文档 以获取更多信息和最佳实践。

pnpm add import-in-the-middle require-in-the-middle

作为变通方法，在项目根目录中创建或修改 .npmrc 文件：

shamefully-hoist=true