跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Source maps 与堆栈跟踪

最后更新 查看 MarkdownAgent 设置

堆栈跟踪(Stack traces) ↗ 可在应用程序遇到未处理异常时帮助调试代码。堆栈跟踪会显示具体调用了哪些函数、调用顺序、来自哪一行和哪个文件,以及使用了哪些参数。

大多数 JavaScript 代码在部署到生产环境前会先打包、通常还会转译,然后进行压缩。此过程会生成更小的 bundle 以优化性能,并在需要时将 TypeScript 代码转换为 JavaScript。

Source maps 将编译和压缩后的代码映射回您编写的原始代码。Source maps 与 JavaScript 运行时返回的堆栈跟踪结合,向您呈现完整的堆栈跟踪。

源映射

从 Wrangler 4.150.0 开始,默认会上传源映射。运行 wrangler deploy、wrangler versions upload或 wrangler preview时,Wrangler 会为 Worker 生成并上传源映射,因此无需任何配置,堆栈跟踪中也会显示原始文件名和行号。

默认情况下,Wrangler 会跳过无法解析的源映射(例如内联 data: 源映射或指向缺失文件的 sourceMappingURL),并继续上传。如需在这种情况下让上传失败,请在 Worker 的 Wrangler 配置中将 upload_source_maps 设为 true:

{
    "upload_source_maps": true
}
upload_source_maps = true

在较早版本的 Wrangler 中,只有将 upload_source_maps 设为 true 才会上传源映射。

cf deploy也默认上传源映射。它会上传构建输出中的所有源映射;对于使用 Cloudflare Vite 插件 1.64.0 或更高版本,或 Wrangler 4.151.0 或更高版本构建的 Worker,cf build 会生成源映射。如需选择不上传,请在构建中禁用源映射。

框架和自定义构建

使用 Vite 或其他构建工具打包 Worker 时,该工具必须生成源映射。Wrangler 只会上传构建输出中已有的映射。

从 1.64.0 版本开始,Cloudflare Vite 插件默认会为Worker 环境生成外部映射,除非你设置了 Vite 的 build.sourcemap 或 Worker 的 upload_source_maps。映射不会添加到客户端环境,因此不会进入公开资源。

在较早版本中,请为 Worker 环境启用外部映射。对于名为 my_worker 的 Worker 环境,请使用:

vite.config.tsts
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
    plugins: [cloudflare()],
    environments: {
        my_worker: {
            build: { sourcemap: true },
        },
    },
});

如果框架将 Worker 分配给该环境,请使用 ssr。启用映射生成后,插件会在输出配置中添加 upload_source_maps: true。显式设置 upload_source_maps: false 会禁用上传。

对于其他构建工具,请生成外部 source map 文件,并在生成的 JavaScript 中保留其 sourceMappingURL 引用。请勿将服务器端 source map 放在公共静态资源目录中。

禁用源映射

如需禁用上传,请将 upload_source_maps 设为 false:

{
    "upload_source_maps": false
}
upload_source_maps = false

也可以向 wrangler deploy 或 wrangler versions upload 传入 --no-upload-source-maps。

使用 Cloudflare Vite 插件时,也可以将 Worker 环境的 build.sourcemap 设为 false。cf deploy 会上传构建输出中的所有源映射,因此使用 cf 项目时,请在构建中关闭源映射生成,以选择不上传。

堆栈跟踪

​​ 当 Worker 抛出未捕获的异常时,我们会获取 source map,并将异常的堆栈跟踪映射回 Worker 原始源代码中的行号。

然后,你可以在流式查看实时日志时,或在 Tail Workers 中查看经过源映射的堆栈跟踪。

Workers Issues 会归类生产环境故障,并在可用时显示捕获的堆栈跟踪。

当 Cloudflare 尝试将堆栈跟踪重新映射到 Worker 的 source map 时,会逐行进行,尽可能多地重新映射。如果堆栈跟踪的某一行因任何原因无法重新映射,Cloudflare 会保持该行不变,并继续处理下一行。

限制

说明 限制
压缩后的 source map 最大大小 15 MiB
编码后(未压缩)的 source map 最大大小 60 MiB

示例

考虑一个简单的项目。src/index.ts 作为应用程序的入口点,src/calculator.ts 定义了一个支持基本算术运算的 ComplexCalculator 类。

  • wrangler.jsonc
  • tsconfig.json
  • src
    • calculator.ts
    • index.ts

让我们看看 source maps 如何简化 ComplexCalculator 类中错误的调试。

未使用 Source Map 重新映射的堆栈跟踪

未上传 source maps:注意所有 JavaScript 代码都被压缩到一个文件中,因此堆栈跟踪缺少文件名信息,显示错误的行号,并且错误地引用 js 而非 ts。

使用 Source Map 重新映射的堆栈跟踪

已上传 source maps:所有方法均引用正确的文件和行号。

相关资源

  • Tail Workers - 了解如何附加 Tail Workers 来转换日志,并将其发送到 HTTP 端点。
  • 实时日志 — 了解如何实时捕获 Workers 日志。
  • RPC 错误处理 — 了解 RPC(远程过程调用)中异常的处理方式。

这篇文档对您有帮助吗?