Wasp 应用接入 Sentry 完整指南服务端与客户端的错误监控实战【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本文档是 Wasp 官方集成指南的中文深度实践版。Wasp 是一个基于 React、Node.js 与 Prisma 的全栈框架支持通过声明式app配置挂载服务端与客户端的启动函数setupFn。本文将带你完整走通在 Wasp 应用中接入 Sentry 的流程创建服务端与客户端两个 Sentry 项目、安装 SDK、配置main.wasp.ts中的setupFn、通过.env.server与.env.client注入 DSN并实现服务端/客户端错误的主动上报、性能监控与 React 错误边界。读完本文你将能在自己的 Wasp 项目中快速复现一套前后端一体的错误追踪体系。前置条件开始之前请确认你已具备以下条件一个已初始化的 Wasp 项目包含main.wasp.ts、src/等标准目录结构一个可用的 Sentry 账号用于创建项目和获取 DSN本文示例基于 Wasp 0.24、sentry/node8、sentry/react8 编写若你使用的版本不同请以对应版本的 SDK 文档为准。为什么用 Wasp 的setupFn接入 Sentry在 Wasp 中应用的启动逻辑初始化第三方 SDK、注册自定义中间件、执行预热任务等统一收敛在app声明的两个钩子里server.setupFn服务端启动函数在 HTTP server 创建之后、正式监听端口之前被调用。client.setupFn客户端启动函数在 React 应用渲染之前执行。从 Wasp 的生成器模板 server/src/server.ts 可以看到setupFn的调用时机非常明确const serverSetupFnContext: ServerSetupFnContext { app, server } await ({ setupFn.importIdentifier } as ServerSetupFn)(serverSetupFnContext)也就是说你的setupServer函数会在 server 创建后、server.listen(port)之前同步执行完毕这正好是注册 Sentry Express 错误处理器setupExpressErrorHandler的理想时机——此时应用尚未开始接收外部请求。客户端侧同理生成模板 sdk/wasp/client/vite/virtual-files/files/routes.tsx 会在路由挂载前执行await setupFn()。因此接入 Sentry 不需要任何框架级特殊适配只需把Sentry.init与错误处理器挂载放进这两个钩子里即可。第一步在 Sentry 创建两个项目Wasp 应用由服务端Node.js/Express和客户端React两部分组成建议为它们分别创建独立的 Sentry 项目便于区分错误来源、单独管理告警规则服务端项目创建项目时平台Platform选择Node.js框架Framework选择Express——Wasp 生成的服务端底层正是 Express 应用。客户端项目创建项目时平台选择React。每个项目创建完成后Sentry 都会提供一个唯一的 DSNData Source Name。DSN 是 Sentry SDK 上报事件所需的地址凭证稍后我们会把它写进环境变量。也可以在 Sentry 控制台的Settings Client Keys (DSN)中随时找到它。第二步安装 Sentry SDK在 Wasp 项目根目录安装两个 SDKnpm install sentry/node sentry/reactsentry/node服务端使用负责捕获 Express 路由、API、操作Operations中的异常并提供setupExpressErrorHandler。sentry/react客户端使用负责捕获浏览器端 React 渲染错误并提供ErrorBoundary组件。第三步在main.wasp.ts中挂载 setup 函数打开项目根目录的main.wasp.ts通过with { type: ref }引用两个 setup 函数并分别挂到server与client字段import { app } from wasp.sh/spec import { setupClient } from ./src/clientSetup with { type: ref } import { setupServer } from ./src/serverSetup with { type: ref } export default app({ name: MyApp, wasp: { version: ^0.24.0 }, title: my-app, head: [link relicon href/favicon.ico /], server: { setupFn: setupServer, }, client: { setupFn: setupClient, }, // ... })关于这两个字段的完整语义可参考 Wasp 官方文档服务端配置说明server.setupFn接收{ app, server }上下文可用于注册自定义路由、初始化资源、启动后台任务等。客户端配置说明client.setupFn会在客户端所有代码执行之前运行也可用于配置 React Query 客户端见configureQueryClient。一个真实的参考实现在 examples/kitchen-sink/src/serverSetup.ts其中使用ServerSetupFn类型注解并在函数内注册自定义路由、预热资源、提交后台 Job验证了setupFn的完整能力边界。第四步配置服务端 Sentry创建src/serverSetup.tsimport * as Sentry from sentry/node; import { ServerSetupFn } from wasp/server; Sentry.init({ dsn: process.env.SENTRY_SERVER_DSN, environment: process.env.NODE_ENV, tracesSampleRate: 1.0, }); export const setupServer: ServerSetupFn async ({ app }) { Sentry.setupExpressErrorHandler(app); };要点说明Sentry.init写在模块顶层这样它在模块加载阶段就会执行早于setupFn被调用确保任何后续引入的模块若抛出异常也能被捕获。setupServer接收的app参数类型是 Express 的Application。Sentry.setupExpressErrorHandler(app)会在 Express 中间件链的末尾注入 Sentry 的兜底错误处理器任何未被捕获的请求异常都会被它接管并上报。从 server/src/server.ts 的生成逻辑可见app由 Wasp 构建的 Express 实例传入因此这里的挂载对 Wasp 的 API、Operations 全部生效。environment: process.env.NODE_ENV让 Sentry 能区分 development / production 环境便于告警与过滤。注意Wasp 对ServerSetupFn的类型定义位于wasp/server与 Operations、Jobs 等模块同属wasp/server/*命名空间。DSN 的查找路径是 SentrySettings Client Keys (DSN)。第五步配置客户端 Sentry创建src/clientSetup.tsimport * as Sentry from sentry/react; Sentry.init({ dsn: import.meta.env.REACT_APP_SENTRY_CLIENT_DSN, environment: import.meta.env.MODE, tracesSampleRate: 1.0, }); export const setupClient async () { // Sentry is initialized above, before the setup function runs. // You can add additional client-side setup here if needed. };要点说明客户端环境变量通过 Vite 的import.meta.env注入REACT_APP_前缀是 Wasp/Vite 客户端环境变量的约定前缀。import.meta.env.MODE对应 Vite 的运行模式development/production可用于区分上报环境。关键约束setupFn必须被定义并导出即使它内部没有任何额外逻辑。因为Sentry.init在模块加载时即执行早于 Wasp 调用 setup 函数而 Wasp 生成器只有在检测到setupFn已定义时才会生成调用代码——如果省略导出整个初始化代码都不会被执行。setupClient还可以承担更多客户端初始化工作比如在 examples/kitchen-sink/src/clientSetup.js 中那样调用configureQueryClient定制 React Query 的全局行为。第六步配置环境变量Wasp 在开发模式下支持两种环境变量文件详见 环境变量文档.env.server提供给服务端进程可存放密钥类敏感信息不提交版本控制。.env.client提供给客户端构建内容会被打包进前端代码任何人都能读到严禁存放密钥。在项目根目录的.env.server中加入SENTRY_SERVER_DSNhttps://your-server-dsnsentry.io/your-project-id在.env.client中加入REACT_APP_SENTRY_CLIENT_DSNhttps://your-client-dsnsentry.io/your-project-id生产环境部署时改为在你的托管平台如 Fly.io、Vercel、Docker 容器上配置同名环境变量即可具体方式可参考 部署环境变量文档。验证集成是否生效测试服务端错误先声明一个自定义 API 端点然后让它抛错。Wasp 中声明 API 分两步详见 自定义 API 端点文档在main.wasp.ts中用api(GET, /test-error, testError)声明路由再在src/apis.ts中实现import { TestError } from wasp/server/api; export const testError: TestError async (req, res) { throw new Error(Test server error for Sentry); };注意TestError的签名是(req, res) void与常规 Operations 不同——它直接面对 Express 的req/res因此你可以在其中调用任何 Express API。由于setupExpressErrorHandler已注册为兜底错误处理器该端点抛出的异常会被自动上报到 Sentry 服务端项目。启动应用wasp start后访问该端点随后在 Sentry 控制台的 Issues 页面中应能看到名为Test server error for Sentry的报错事件并带有完整的堆栈信息。测试客户端错误在任一页面组件中添加一个触发异常的按钮export const MainPage () { const handleError () { throw new Error(Test client error for Sentry); }; return ( div button onClick{handleError}Test Sentry Error/button /div ); };点击按钮后React 渲染流程中的错误会被 Sentry 的全局处理器捕获并上报到客户端项目。若想让 UI 层面更优雅地降级可进一步使用下面的Sentry.ErrorBoundary包裹应用。进阶配置为错误补充用户上下文对于登录态应用把当前用户信息附加到上报事件中能显著加快问题定位。在 Operations 或 API 处理器中通过 Wasp 的context.user获取当前用户并调用Sentry.setUserimport * as Sentry from sentry/node; // In your API handlers or operations export const someOperation async (args, context) { if (context.user) { Sentry.setUser({ id: context.user.id, email: context.user.email, }); } // ... };context.user由 Wasp 的认证机制注入前提是应用已启用 Wasp Auth 且该 Operation 需要登录态。这样 Sentry 事件详情页会展示出报错用户的 id 与邮箱便于按用户维度筛选问题。开启性能监控与 ProfilingtracesSampleRate控制事务Transaction的采样比例用于链路追踪profilesSampleRate控制性能剖析Profiling的采样比例。生产环境建议调低采样率以控制成本与数据量Sentry.init({ dsn: your-dsn, tracesSampleRate: 0.1, // Capture 10% of transactions profilesSampleRate: 0.1, // Capture 10% of profiles (if using profiling) });开发环境可使用tracesSampleRate: 1.0100% 采样方便调试生产环境按业务量级通常建议 0.10.2。完整参数可查阅 Sentry SDK 文档。使用 React 错误边界兜底 UI用Sentry.ErrorBoundary包裹应用当渲染过程中抛出错误时用户会看到降级提示而非白屏import * as Sentry from sentry/react; export const App ({ children }) { return ( Sentry.ErrorBoundary fallback{pAn error occurred/p} {children} /Sentry.ErrorBoundary ); };注意Sentry 的 ErrorBoundary 只负责渲染错误与生命周期错误事件处理函数如按钮onClick中抛出的同步错误不会自动进入 ErrorBoundary此时由 SDK 的全局onerror处理器捕获。因此实践中两种手段往往搭配使用全局初始化捕获所有未处理异常 ErrorBoundary 提供 UI 降级。小结通过以上六个步骤你已经为 Wasp 应用建立了完整的 Sentry 错误追踪链路main.wasp.ts中的server.setupFn与client.setupFn是唯一需要改动的框架入口二者分别承载sentry/node与sentry/react的初始化DSN 通过.env.server/.env.client按环境注入异常上报后可在 Sentry 控制台按用户、环境、采样率等维度分析。这套模式同样适用于其他监控类 SDK 的接入——把第三方初始化放进 Wasp 的启动钩子是集成一切外部服务的通用范式。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考