堆栈跟踪(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 环境,请使用:
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 maps:注意所有 JavaScript 代码都被压缩到一个文件中,因此堆栈跟踪缺少文件名信息,显示错误的行号,并且错误地引用 js 而非 ts。
已上传 source maps:所有方法均引用正确的文件和行号。
- Tail Workers - 了解如何附加 Tail Workers 来转换日志,并将其发送到 HTTP 端点。
- 实时日志 — 了解如何实时捕获 Workers 日志。
- RPC 错误处理 — 了解 RPC(远程过程调用)中异常的处理方式。