Encore Toolbar 接入指南在前端直接查看 API 请求、分布式 Trace 与后端日志【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore Toolbar 是 Encore 提供的一个轻量级、可一行接入的前端开发面板脚本把它加到你的 HTML 里它就会自动拦截页面上的所有fetch()与XMLHttpRequest请求从 Encore 后端返回的响应头中捕获 Trace ID并让你一键跳转到 Development Dashboard 或 Encore Cloud 中的对应分布式追踪。本文基于 docs/go/how-to/encore-toolbar.md 完整展开结合本仓库的 Go 运行时源码runtimes/go/appruntime/apisdk与 CLI 源码cli/cmd/encore/daemon讲清楚安装方式、参数含义、底层工作机理以及请求不拦截、Trace 链接失效、后端日志不加载三类常见问题的排查步骤帮助你为前端 Encore 后端的开发工作流建立零切换的观测体验。为什么要用 Encore Toolbar在开发一个前端调用 Encore 后端的应用时排查问题往往需要在前端控制台、后端日志、追踪系统之间来回切换。Encore Toolbar 的价值在于把这一过程收敛到一个浮动的开发者面板中它自动拦截页面内所有经fetch()和XMLHttpRequest发出的请求它从 Encore 的响应头中读取 Trace ID把前端每个请求与后端的一次完整分布式追踪关联起来它提供直达链接跳到 Development Dashboard本地或 Encore Cloud部署环境查看该请求的完整 Trace在本地开发时它还能通过 Encore daemon实时拉取该 Trace 对应的后端日志。简而言之当你正在构建一个对接 Encore 后端的前端时无需切换到其他工具就能看到后端到底发生了什么。安装一行 script 标签接入Encore Toolbar 以单个script标签的形式引入 HTML脚本加载后会自动初始化并开始拦截请求script srchttps://encore.dev/encore-toolbar.js/script自动检测与显式参数脚本默认通过请求来源origin上的/__encore/healthz端点自动探测你的 App ID 与所在环境。如果自动检测失效例如前端与后端之间存在代理且/__encore/healthz没有被暴露出来可以在 script 标签上显式传入这两个参数script srchttps://encore.dev/encore-toolbar.js?appIdmy-appenvNamestaging/script参数说明如下参数说明appId你的 Encore 应用 slug即app.encore.devURL 中显示的那个标识。envName环境名称例如staging、production。除了在 script 标签上设置也可以在 Toolbar 的Settings 面板中随时修改这两个值。关键加载顺序与 async/defer 限制需要注意脚本会在解析parse阶段直接对window.fetch和XMLHttpRequest进行打补丁patch因此它必须先于你的应用代码加载并且不能带async或defer属性。一些 HTTP 库如 Axios在初始化时会保存一份fetch的引用如果该库先于 Toolbar 脚本加载这些请求将不会被拦截。建议把 script 标签放在head中尽可能靠前的位置。提示只有响应中带有x-encore-trace-id头的请求才会出现在 Toolbar 里详见下一节。工作原理从响应头到分布式 Trace后端如何产生 Trace IDToolbar 的拦截逻辑依赖一个约定当你的前端向 Encore 后端发起请求时后端会在响应中返回x-encore-trace-id响应头Toolbar 读取该头并记录这次请求及其 Trace ID只有带这个头的请求才会出现在 Toolbar 中。这一行为在仓库的 Go 运行时中有明确的源码实现。在 runtimes/go/appruntime/apisdk/api/services.go#L11-L44 中每个服务 handler 适配器都会把当前请求元数据中的 Trace ID 写回响应// Extract metadata from the request. meta : CallMetaFromContext(req.Context()) // Always send the trace id back. traceIDStr : meta.TraceID.String() w.Header().Set(X-Encore-Trace-ID, traceIDStr)而 Trace ID 本身是 16 字节的随机值定义于 runtimes/go/appruntime/exported/model/trace.go#L10-L24String()方法将其以 base32 编码无填充输出type ( TraceID [16]byte SpanID [8]byte ) func (id TraceID) String() string { if id.IsZero() { return } return b32.EncodeToString(id[:]) }也就是说Toolbar 拿到的是一个 16 字节随机 ID 的可读编码形式前端与后端通过这个 ID 共享同一条追踪链路。自动检测依赖的 /__encore/healthzToolbar 通过请求来源上的/__encore/healthz端点自动探测 App ID 与环境名称。这个端点由 Encore 运行时在每个应用中统一注册见 runtimes/go/appruntime/apisdk/api/encore_routes.go#L12-L16func (s *Server) registerEncoreRoutes() { s.encore.HandlerFunc(wildcardMethod, /healthz, s.handleHealthz) s.encore.Handle(POST, /pubsub/push/:subscription_id, s.handlePubsubPush) s.encore.Handle(POST, /authhandler, s.handleRemoteAuthCall) }其响应体见同文件 L49-L73返回app_slug、env_name、app_revision、deploy_id等 JSON 字段Toolbar 正是从这里拿到构建 Trace 链接所需的 App ID 与环境名{ code: ok, message: Your Encore app is up and running!, details: { app_slug: my-app, env_name: staging, app_revision: ..., deploy_id: ..., checks: [] } }Toolbar 为每个捕获的请求展示什么对每个捕获到的请求Toolbar 会展示方法与 URL请求的 HTTP 方法与完整 URL状态码响应状态请求与响应体自动捕获查询参数与 Cookie从请求 URL 与document.cookie解析Trace 链接直达该 Trace 的链接——本地环境指向 Development Dashboard部署环境指向 Encore Cloud后端日志本地运行时Toolbar 会连接本地 Encore daemon并展示所选 Trace 对应的后端日志输出。故障排查请求没有被拦截Toolbar 只捕获返回了x-encore-trace-id响应头的请求。如果你的请求没有出现在 Toolbar 中按以下顺序排查确认响应头存在。打开浏览器 Network 面板选中一个发往 Encore 后端的请求在响应头中查找x-encore-trace-id。如果该头缺失说明请求没有经过 Encore 的请求处理链路例如它可能命中了非 Encore 服务器或经过了一个会剥离该头的反向代理。可以参考上文 源码中的写入位置 确认头名称拼写无误。确保脚本先于应用加载。Toolbar 在解析阶段对fetch和XMLHttpRequest打补丁。如果你的应用代码先于脚本运行早期的那些请求就不会被捕获。把script标签移到应用 bundle 之前。检查脚本报错。打开浏览器控制台查找与 Toolbar 脚本相关的错误。脚本加载失败例如被内容安全策略 CSP 拦截会导致它无法完成初始化。Trace 链接无法创建如果 Toolbar 显示Trace link could not be created说明它缺少足够的信息来构造链接——它需要同时具备App ID和环境名并会尝试从请求来源的/__encore/healthz端点自动探测这两个值。可以按以下方式解决显式传入参数。最简单的修复是在 script 标签上直接设置appId和envNamescript srchttps://encore.dev/encore-toolbar.js?appIdmy-appenvNamestaging/script如果不想把环境名硬编码进 HTML可以在后端添加一个 raw endpoint让它带着正确参数重定向到 Toolbar 脚本package toolbar import ( fmt net/http net/url encore.dev ) //encore:api public raw path/encore-toolbar.js func Toolbar(w http.ResponseWriter, req *http.Request) { meta : encore.Meta() target : fmt.Sprintf( https://encore.dev/encore-toolbar.js?appId%senvName%s, url.QueryEscape(meta.AppID), url.QueryEscape(meta.Environment.Name), ) http.Redirect(w, req, target, http.StatusFound) }然后把 script 标签指向你自己的后端script srchttps://your-api.com/encore-toolbar.js/scriptencore.Meta()中的AppID与Environment.Name是 Encore 运行时注入的当前部署元信息天然适配不同环境无需在代码里写死环境名。确认 healthz 可达。Toolbar 通过调用请求来源上的/__encore/healthz来自动探测 App ID 和环境名。如果你的前端与 Encore 后端之间存在反向代理或 API 网关/__encore/healthz可能没有暴露出来。此时要么配置代理把/__encore/healthz转发到后端要么在 script 标签上显式传入appId与envName。在 Toolbar 中手动设置。打开 Toolbar 的 Settings 面板手动填写 App ID 与环境名字段。后端日志不加载后端日志流式输出仅在本地运行时可用Toolbar 会通过 WebSocket 连接本地 Encore daemonlocalhost:9400来按 Trace 拉取日志。这个 9400 端口正是 Encore CLI 本地开发服务的 Dashboard 端口见 cli/cmd/encore/daemon/daemon.go#L128-L131d.Dash d.listenTCPRetry(dashboard, env.EncoreDevDashListenAddr(), 9400)README 中对此也有说明运行encore run后本地开发面板即位于localhost:9400见 README.md#L137-L139。排查步骤确保应用正在运行。后端日志依赖encore run处于活动状态。确认环境。日志流式输出仅对local环境可用。在部署环境中请通过 Trace 链接到 Encore Cloud 查看日志。确认 App ID 已设置。Toolbar 需要一个有效的 App ID 才能向 daemon 请求日志。如果/__encore/healthz不可达请通过 script 标签或在 Toolbar 的 Settings 中设置 App ID。小结Encore Toolbar 的接入成本极低——一行script标签即可但它把前端请求 → 后端 Trace → 后端日志整条链路收进了同一个浮动面板是开发前端 Encore 后端应用时非常有用的观测入口。使用时的三个关键点是脚本必须放在head最前且不带async/defer否则打补丁时机失效请求必须带x-encore-trace-id响应头才会被捕获这是 Encore 运行时在 services.go 中统一写回的Trace 链接与本地日志分别依赖/__encore/healthz的可达性与本地encore run进程。如果自动检测因代理等环境受限显式传入appId与envName或用上文提供的 raw endpoint 重定向方案即可稳定工作。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考