后端Web框架SSR【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址https://gitcode.com/gh_mirrors/vi/vinext点击查看免费下载Vinext 通过 changeset 04a868a4157123111a1b9f0197014f4280bb8d90.md 引入了一项核心能力在 App Router 与 Pages Router 全链路中内置发射 request、rendering、fetch、metadata、response 五类框架级 span对应 PR #3296。本指南以官方文档 docs/tracing.mdx 为主线结合 packages/vinext/src/server 下的源码实现带你掌握 Vinext 与 Next.js 完全一致的 Tracing 接入方式、稳定的next.*span 属性协议以及如何同时对接 OpenTelemetry、Sentry 与 Cloudflare Workers 原生 trace最终得到一套可运行、可排查、可扩展的线上可观测性方案。一、功能定位不新增 API只复用 Next.js 约定Vinext 的设计原则是兼容即接入它不引入 vinext 专属的 tracing API也不需要任何 vinext 专用的适配器。凡是 Next.js 应用已有的instrumentation.ts/instrumentation.js入口、register()、onRequestError、withSentryConfig等约定在 Vinext 上原样可用。在源码层面这一兼容性由一套统一的框架 tracer承载核心实现在 packages/vinext/src/server/framework-tracer.ts它定义了一套与具体后端解耦的FrameworkTracingIntegration接口enterSpan、getActiveSpan、withPropagatedContext、runWithDetachedContext等。集成注册表位于 packages/vinext/src/server/tracer.ts默认注册 OpenTelemetry 后端opentelemetry-tracing.ts并以Symbol.for(vinext.frameworkTracing.integrations)挂载在全局对象上从而允许多个后端如 OpenTelemetry Workers 原生 tracing围绕同一个回调同时进入各自的上下文。这套抽象的收益是无论应用选择哪条观测链路框架 span 的名称与属性始终一致可观测性语义不会因部署平台不同而漂移。二、应用接入与 Next.js 完全相同的 instrumentation.ts2.1 注册 OpenTelemetry SDK在你的应用根目录放置标准的instrumentation.ts注册方式与 Next.js 完全一致// instrumentation.ts import { registerOTel } from vercel/otel; export function register() { registerOTel({ serviceName: my-app }); }vercel/otel与 exporter 属于应用自身的依赖Vinext 不强制安装任何 OpenTelemetry 包。这意味着未安装任何 SDK 的应用不会报缺失依赖错误会走一条廉价的 no-op OpenTelemetry 路径即集成列表为空时的空转分支见 framework-tracer.ts 中enter(0)直接回调的降级逻辑已接入sentry/nextjs等标准集成的应用可继续通过同一个全局 OpenTelemetry API 注册 provider并保留原有的register()与onRequestError配置无需改动。2.2 register() 的执行时机与 ESM loaderVinext 会在受追踪的生产用户模块求值之前完成register()保证 SDK 初始化先于业务代码执行span 才能被正确采集。在普通 Node 构建下若应用直接安装了可解析、未被转译的opentelemetry/instrumentationVinext 还会在用户模块求值前注册自己的 ESM loader用于捕获后续 import 的自动插桩。除此之外的 instrumentation loader 仍由应用自己管理——Vinext 不越权干预应用侧依赖。三、框架 Span 协议稳定的 next.* 属性3.1 每个框架 span 都携带的属性官方文档明确每一个由框架产生的 span 都包含以下三个稳定属性供查询、聚合与 Alert 使用属性含义next.span_category固定为nextjsnext.span_namespan 的最终名称next.span_type下述 span 类型之一这一协议在源码中有直接对应resolveDescriptor会为每个描述符自动注入这三个属性且updateName在重命名时同步刷新next.span_name见 framework-tracer.ts 与 framework-tracer.ts。错误场景下recordFrameworkSpanError还会补写error.type依据错误对象构造名推断并调用recordException/setErrorStatus见 framework-tracer.ts且默认对 promise rejection 与同步异常均生效recordErrors默认为true。3.2 请求根 spanBaseServer.handleRequest每个请求的根 span 类型为BaseServer.handleRequest实现见 request-tracing.ts开始时记录http.method与http.target请求路径span kind 为server请求处理过程中随着路由匹配与 RSC 判定推进逐步记录参数化后的http.route与next.route、next.rsc结束时记录http.status_code出错时记录error.type最终next.span_name遵循 Next.js 惯例例如GET /blog/[slug]或RSC GET /blog/[slug]RSC 前缀表示 Flight 数据请求。这里有一个平台差异需要留意OpenTelemetry 后端会实时更新 span 的显示名称而 Cloudflare Workers 的 custom-span API不支持重命名已启动的 span因此 Workers 上该 span 的显示名会保持初始的 HTTP 方法如GET路由限定信息通过最终属性next.span_name提供——查询 trace 时应以属性为准。3.3 内置子 span 类型表官方文档给出的完整内置子 span 类型如下两类 Router 均覆盖App RouterPages RouterAppRender.getBodyResultRender.getServerSidePropsAppRender.fetchRender.getStaticPropsAppRouteRouteHandlers.runHandlerRender.renderDocumentResolveMetadata.generateMetadataNode.runHandlerNextNodeServer.findPageComponentsNextNodeServer.findPageComponentsNextNodeServer.getLayoutOrPageModule—NextNodeServer.createComponentTree—NextNodeServer.startResponse—各类型的源码出处均可在 packages/vinext/src/server 中逐一验证渲染AppRender.getBodyResultapp-page-tracing.ts取数AppRender.fetch的 span 名称形如fetch METHOD url属性含http.method、http.url、net.peer.name、net.peer.port结束后补记http.status_codekind 为clientapp-fetch-tracing.ts元数据ResolveMetadata.generateMetadataapp-metadata-tracing.ts路由处理AppRouteRouteHandlers.runHandlerapp-route-handler-execution.ts组件树NextNodeServer.getLayoutOrPageModule与NextNodeServer.createComponentTreeapp-page-tracing.ts响应NextNodeServer.startResponseresponse-start-tracing.tsPages 侧Render.getServerSideProps/Render.getStaticProps的 span 名称带路由如getServerSideProps /blog/[slug]Render.renderDocument命名为render route (pages) ...Node.runHandler命名为executing api route (pages) ...NextNodeServer.findPageComponents命名为resolve page components并携带next.route属性全部见 pages-execution-tracing.ts。值得注意的一个实现细节Pages Router 的Render.renderDocument会先返回 HTML shell但 span 会通过deferUntilStreamConsumed保持打开直到 body 流消费完毕见 pages-execution-tracing.ts确保流式渲染的耗时被完整计入。3.4 环境变量开关环境变量作用NEXT_OTEL_FETCH_DISABLED1关闭 Vinext 的AppRender.fetchspan。当其他 agent如 Sentry、自定义 HTTP 插桩已经在插桩fetch时使用避免重复 spanapp-fetch-tracing.tsNEXT_OTEL_VERBOSE1当前不会启用任何额外的 vinext span内置集合保持不变请勿依赖该变量期待更多 span四、上下文传播与 clientTraceMetadataVinext 通过应用 OpenTelemetry SDK 注册的 propagator提取入站上下文对应withPropagatedContext(headers, ...)调用见 request-tracing.ts。因此应用在请求内自行创建的 OpenTelemetry span 会自动继承 vinext 请求 span形成正确的父子层级experimental.clientTraceMetadata通过 Next.js 常规配置与集成包装器即可生效无需额外适配静态或缓存的 HTML 不会残留其他请求的传播元数据避免 trace 上下文在缓存复用时的串扰。五、Sentry 集成零迁移成本已有 Next.js 应用的 Sentry 配置可原样保留Vinext 提供与 Next.js 相同的公共 API// instrumentation.ts import * as Sentry from sentry/nextjs; export function register() { Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1, }); } export const onRequestError Sentry.captureRequestError;// next.config.ts import { withSentryConfig } from sentry/nextjs/config; import type { NextConfig } from next; const nextConfig: NextConfig {}; export default withSentryConfig(nextConfig, { silent: !process.env.CI, });Sentry SDK 通过这套既有接入注册其 OpenTelemetry provider即可收到上述请求根 span 与全部内置子 span。再次强调Sentry 与应用同属可选项——安装 vinext 不会顺带安装 Sentry 或 OpenTelemetry 包未接入 Sentry 的应用不会因此产生任何缺失依赖或额外开销。六、Cloudflare Workers 原生 traces6.1 同一个调用点双上下文同时进入在 Cloudflare Workers 上框架 span 的调用点与 Node 环境完全相同同一套frameworkTracer.trace并不存在独立的 Workers 请求生命周期实现。区别在于Vinext 会把每个逻辑 span 同时送入已注册的 OpenTelemetry provider与Workers 原生 tracing 上下文。你可以用应用自定义 span 包住 vinext 入口而 vinext 内部以及路由代码里产生的自定义 span、fetch、绑定调用都会继承当前活跃 spanimport { tracing } from cloudflare:workers; import handler from vinext/server/fetch-handler; export default { fetch(request: Request, env: Cloudflare.Env, ctx: ExecutionContext) { return tracing.enterSpan(app.request, () handler.fetch(request, env, ctx)); }, };6.2 开启 trace 记录Workers 原生 trace需要显式开启在wrangler.jsonc中配置{ observability: { traces: { enabled: true, }, }, }开启后生成的层级可能包含Workers handler 根 → 应用自定义 span → vinext 的BaseServer.handleRequest与内置子 span → 路由代码中的另一个应用 span → 自动的 fetch、KV、D1、R2 或其它 binding span。6.3 双后端并存的行为若应用同时注册了 OpenTelemetry provider 与 Workers 原生 tracing则两个消费方看到的子 span 名称与next.*属性完全一致但各自持有独立的 trace 与 span ID每个集成独立生成。这意味着在 Workers 控制台看原生 trace与在 OTLP/Sentry 后端看 OpenTelemetry trace语义相同、ID 不同属预期行为Workers 原生 tracing 的观测产物可通过 Workers Observability保留或导出到配置的 OpenTelemetry 目标包括 Sentry无需仅为 Workers 原生链路在进程内再加装 Sentry SDK相关行为在测试套件中有覆盖可参考 workers-tracing.test.ts。6.4 跨服务传播的限制Workers 原生 tracing 目前不会自动向 Cloudflare 之外的服务传播 W3C trace context。如果业务需要跨服务如调用自建后端串联 trace应使用应用自有的 OpenTelemetry fetch/HTTP 插桩或显式的 propagator 注入而不是依赖 Workers 原生上下文。七、采样、保留与导出留给部署层的决定Vinext 在生成的工程中不会静默开启 trace 记录也不会自行配置任何 exporter。采样率、trace 保留时长、导出目标Sentry、自建 OTLP Collector、Workers Observability 等全部属于部署层的选择由应用与平台配置共同决定。这一设计保证了默认零开销未接入 SDK、未开启观测时走 no-op 路径控制权透明框架只负责发射稳定语义的 span不替应用做任何采样/导出决策排查成本低span 名称与属性协议固定前端可观测性团队可据此沉淀统一的 dashboard 与告警规则。八、小结围绕 changeset #3296 引入的内置 span 体系Vinext 在 App Router 与 Pages Router 上提供了与 Next.js 语义对齐的 Tracing 能力统一的next.*属性协议、固定命名的内置子 span、双后端OpenTelemetry Workers 原生同时进入。接入方只需沿用标准的instrumentation.ts/registerOTel/withSentryConfig即可在本地 Node 与 Cloudflare Workers 上获得一致的可观测性体验而无须为 Vinext 学习任何新 API。官方完整指南见 docs/tracing.mdx核心实现入口为 framework-tracer.ts对应单元测试可参阅 framework-tracer.test.ts、request-tracing.test.ts、app-fetch-tracing.test.ts 与 pages-execution-tracing.test.ts。赞分享后端Web框架SSR【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址https://gitcode.com/gh_mirrors/vi/vinext点击查看免费下载相关推荐cmatrix 安装使用终极指南手把手打造终端数字雨效果cmatrix 安装使用终极指南手把手打造终端数字雨效果 你是否曾幻想过在终端里重现《黑客帝国》中那倾泻而下的数字雨cmatrix 正是这样一款开源的终端工后端Web框架SSRCloudflare Workers 自动追踪兼容性标志Automatic tracing完全指南从 Wrangler 配置到 OpenTelemetry 导出Cloudflare Workers 自动追踪兼容性标志Automatic tracing完全指南从 Wrangler 配置到 OpenTelemetry文档AI-Scientist-v2替你自主写论文的自动化科研系统AI Scientist v2替你自主写论文的自动化科研系统 跑完一组实验结果要两天想法清单还卡在“换个注意力模块试试”AI Scientist v2 把人工智能AI Agent自主智能体科研Agent 工作流上一篇DevOps工具链整合DevOps Interview Guide中的CI/CD工具集成案例下一篇如何为Remarkable开发自定义扩展Python Markdown扩展开发指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
