在前端使用 Encore Toolbar拦截 API 请求、查看 Trace 与后端日志的轻量调试面板【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore Toolbar 是 Encore 提供的一段轻量级、即插即用的前端调试脚本把它放入前端页面后它会自动拦截所有fetch()与XMLHttpRequest请求从 Encore 后端返回的x-encore-trace-id响应头中提取 Trace ID并在页面上呈现一个悬浮开发者面板。本指南将带你完成 Toolbar 的安装与参数配置讲解它捕获请求、生成 Trace 链接、流式加载后端日志的底层原理并给出常见问题的排查方案让你在开发前后端分离应用时无需切换到单独工具即可透视后端行为。Encore Toolbar 能做什么当你在构建一个与 Encore 后端通信的前端应用时往往需要在浏览器、命令行与调试面板之间来回切换才能弄清楚一次请求在后端究竟发生了什么。Encore Toolbar 正是为此设计的悬浮开发者面板自动拦截前端发出的所有fetch()与XMLHttpRequest调用从 Encore 后端响应中捕获 Trace IDx-encore-trace-id响应头一键跳转到对应 Trace —— 本地开发时打开 Development Dashboard部署环境中跳转到 Encore Cloud本地运行时还能直接读取后端日志输出。它是一段“drop-in”脚本无需改动后端代码、无需安装 npm 依赖只需在 HTML 中引入一个script标签即可。安装一行脚本标签接入在 HTML 中引入一个script标签Toolbar 会自动初始化并开始拦截请求script srchttps://encore.dev/encore-toolbar.js/scriptApp ID 与环境名的自动检测Toolbar 会通过调用每个请求源origin上的/__encore/healthz端点来自动检测你的 App ID 与环境名。Encore 运行时在每个服务进程中都内置了该健康检查路由返回的 JSON 中包含app_slugApp ID与env_name环境名等字段详见 healthz.rs。如果自动检测不可用——例如前端与后端之间存在代理且/__encore/healthz没有被暴露——你可以把参数显式传给脚本script srchttps://encore.dev/encore-toolbar.js?appIdmy-appenvNamestaging/script参数说明appId你的 Encore 应用 slug即app.encore.dev链接中的那一段标识。envName环境名称例如staging、production。你也可以稍后在 Toolbar 的Settings设置面板中随时设置或修改这两个值。加载时机必须在应用代码之前、且不能异步加载Toolbar 脚本在解析parse时就为window.fetch和XMLHttpRequest打补丁。因此它必须在你的应用代码之前加载不带async或defer属性。需要注意部分 HTTP 库例如 Axios在初始化时会缓存fetch的引用如果库先于 Toolbar 脚本加载那么后续经它发出的请求将不会被拦截。稳妥做法是把脚本标签尽可能放在head的最前面。工作原理Trace ID 如何被捕获与利用x-encore-trace-id响应头当前端向 Encore 后端发起请求时后端会在响应中带上x-encore-trace-id头。Toolbar 读取该头并记录请求及其对应的 Trace ID——只有携带该响应头的请求才会出现在 Toolbar 中。这一行为在源码中可以得到印证。Encore 的核心运行时Rust 实现在请求处理完成、即将返回响应时会把当前请求的 Trace ID 序列化后写入响应头if let Ok(val) HeaderValue::from_str(request.span.0.serialize_encore().as_str()) { encoded_resp.headers_mut().insert(x-encore-trace-id, val); }见 runtimes/core/src/api/endpoint.rs。同样网关Gateway在向上游转发请求、组装响应时也会通过maybe_add_trace_id_header补上该头若响应头中已存在则不会覆盖相关单元测试见 runtimes/core/src/api/gateway/mod.rsfn maybe_add_trace_id_header(resp: mut ResponseHeader, trace_id: model::TraceId) { if resp.headers.contains_key(x-encore-trace-id) { return; } let value trace_id.serialize_encore(); if let Ok(val) HeaderValue::from_str(value.as_str()) { let _ resp.insert_header(x-encore-trace-id, val); } }这也解释了故障排查中反复出现的原则如果响应里没有x-encore-trace-idToolbar 就不会捕获该请求。/__encore/healthz与自动检测的底层支撑Toolbar 的自动检测依赖/__encore/healthz端点它是 Encore 运行时内置的“保留路由”。网关在request_filter阶段会直接匹配并响应该路径见 runtimes/core/src/api/gateway/mod.rs健康检查处理器返回如下结构的 JSON见 healthz.rs{ code: ok, message: Your Encore app is up and running!, details: { app_slug: my-app, env_name: local, app_revision: …, deploy_id: … } }Toolbar 正是从details中读取app_slug与env_name来完成自动检测的。本地开发时Supervisor 代理同样处理/__encore/healthz路径见 supervisor/src/proxy.rsCLI 在encore run启动服务后也会轮询该端点以确认应用就绪见 cli/daemon/run_spec.go。每条捕获请求的展示内容对每一条被捕获的请求Toolbar 会展示Method 与 URL—— HTTP 方法及完整请求地址状态码—— 响应状态请求体与响应体—— 自动捕获查询参数与 Cookie—— 从请求 URL 与document.cookie解析Trace 链接—— 指向 Development Dashboard本地或 Encore Cloud部署环境中对应 Trace 的直接链接后端日志—— 本地运行时Toolbar 通过 WebSocket 连接本地 Encore daemonlocalhost:9400拉取所选 Trace 对应的后端日志输出。故障排查请求未被拦截Toolbar只捕获返回了x-encore-trace-id响应头的请求。如果请求没有出现在 Toolbar 中按以下顺序排查确认响应头存在。打开浏览器 Network 面板选中一条发往 Encore 后端的请求在响应头Response Headers中查找x-encore-trace-id。如果该头缺失说明请求并没有经过 Encore 的请求处理链路——例如它可能命中了一个非 Encore 服务器或者被反向代理剥掉了响应头。确保脚本先于应用加载。Toolbar 在解析时给fetch和XMLHttpRequest打补丁如果你的应用代码先于脚本执行那么早期的请求不会被捕获。把script标签移到应用 bundle 之前即可。检查脚本报错。打开浏览器控制台查找与 Toolbar 脚本相关的错误。脚本加载失败例如被 Content Security Policy 拦截会导致其无法初始化。Trace 链接无法创建如果 Toolbar 提示 “Trace link could not be created”说明它缺少构建链接所需的信息——Toolbar 需要同时具备 App ID 与环境名并默认从请求源的/__encore/healthz端点自动检测这两项。显式传递参数。最简单的修复方式是在脚本标签上直接设置appId与envNamescript srchttps://encore.dev/encore-toolbar.js?appIdmy-appenvNamestaging/script如果你不想硬编码环境名可以增加一个后端端点重定向到携带正确参数的 Toolbar 脚本import { api } from encore.dev/api; import { appMeta } from encore.dev; export const toolbar api.raw( { method: GET, expose: true, path: /encore-toolbar.js }, async (req, resp) { const appId appMeta().appId; const envName appMeta().environment.name; const url https://encore.dev/encore-toolbar.js?appId${encodeURIComponent(appId)}envName${encodeURIComponent(envName)}; resp.writeHead(302, { Location: url }); resp.end(); }, );然后把脚本标签指向你自己的后端script srchttps://your-api.com/encore-toolbar.js/script注意上述示例使用了 Encore 的api.raw原始端点与appMeta()运行时元数据App ID 与环境名由部署上下文注入将环境名自动注入脚本 URL从而避免硬编码。这是 Encore TypeScript 运行时 encore.dev/api 提供的原生能力。检查 healthz 是否可达。Toolbar 通过在请求源上调用/__encore/healthz自动检测 App ID 与环境名。如果你的前端与 Encore 后端之间存在反向代理或 API 网关/__encore/healthz可能没有通过它暴露出来。此时要么配置代理把/__encore/healthz转发到后端要么在脚本标签上显式传入appId与envName。在 Toolbar 中手动设置。打开 Toolbar 的 Settings 面板手动填写 App ID 与环境名字段。后端日志不加载后端日志的流式读取只在本地运行时生效Toolbar 通过 WebSocket 连接本地 Encore daemonlocalhost:9400来获取指定 Trace 的日志。排查步骤确认应用正在运行。后端日志依赖encore run处于激活状态——本地开发时 daemon 负责运行你的应用并对外提供日志流。确认环境。日志流仅对local环境可用。在部署环境中请使用 Trace 链接跳转到 Encore Cloud 查看日志。确认 App ID 已设置。Toolbar 需要有效的 App ID 才能向 daemon 请求日志。如果/__encore/healthz不可达请通过脚本标签或在 Toolbar 的 Settings 中设置 App ID。小结Encore Toolbar 把“前端发出的请求 → 后端的 Trace → 后端的日志”串成了一条完整的可观测链路一段script完成接入/__encore/healthz自动识别应用与环境的身份x-encore-trace-id响应头成为前后端联动的信标。结合 Development Dashboard、分布式追踪与日志相关文档你可以在本地开发中真正做到“不离开页面就能看懂后端”。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考