企业官网建设流程全解析

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 项目中接入 Sentry 后，服务端（Node.js）和客户端（React）发生的错误会分别上报到两个不同的 Sentry 项目，从而可以集中查看线上和开发环境中的异常。本指南基于 Wasp 官方文档 web/docs/guides/integrations/sentry.md，该指南标注在 Wasp 0.24、@sentry/node8、@sentry/react8 下验证过。

准备条件

• 一个已经可以运行的 Wasp 项目（创建和运行方式见 快速开始）。
• 一个 Sentry 账号。

在 Sentry 中创建两个项目

Sentry 要求为 Wasp 应用分别创建两个项目（来源：sentry.md）：

1. 服务端项目：平台选择Node.js，框架选择Express。
2. 客户端项目：平台选择React。

每个项目创建完成后都会分配一个唯一的 DSN（Data Source Name），后文的配置文件就依赖这两个 DSN。文档同时说明，可以在 Sentry 的Settings > Client Keys (DSN)页面查看 DSN。

安装 Sentry 包

在项目根目录执行：

npm install @sentry/node @sentry/react

@sentry/node负责服务端错误上报，@sentry/react负责客户端错误上报。

在 main.wasp.ts 注册 setup 函数

Wasp 提供了服务端和客户端两个 setup 函数入口：server.setupFn在服务启动时执行（见 Server Config），client.setupFn在客户端初始化最早阶段执行（见 Client Config）。在main.wasp.ts中把两个函数引用进去：

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", // ... server: { setupFn: setupServer, }, client: { setupFn: setupClient, }, })

编写服务端 Sentry 配置

新建src/serverSetup.ts（JavaScript 项目对应.js文件）：

import * 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); };

要点说明：

• dsn通过环境变量SENTRY_SERVER_DSN注入，避免把 DSN 硬编码进代码。
• Sentry.setupExpressErrorHandler(app)把 Sentry 的错误处理器挂到 Wasp 服务端的 Expressapp上，之后服务端抛出的错误才能被捕获上报。
• tracesSampleRate: 1.0表示 100% 采样 trace，可按需调整（见文末“可选的进阶配置”）。

编写客户端 Sentry 配置

新建src/clientSetup.ts：

import * 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.init 在模块加载时就已执行 };

文档特别强调：setupFn即使没有额外逻辑也必须定义并导出，因为Sentry.init是在模块加载时运行的，这发生在 Wasp 调用 setup 函数之前。另外，Client Config 提到客户端 setup 函数在启用 prerendering 时也可能在服务端渲染阶段执行，如果你的 setup 里后续加入浏览器专属逻辑（如window、localStorage），需要用import.meta.env.SSR判断。

配置环境变量

按照 Env Variables 的说明，Wasp 项目根目录可以用.env.server存放服务端变量、.env.client存放客户端变量：

.env.server（服务端 DSN，属于敏感信息，文档建议不要提交到版本库）：

SENTRY_SERVER_DSN=<替换为你服务端项目的 DSN>

.env.client（客户端 DSN，客户端变量必须以REACT_APP_为前缀才会被注入客户端代码）：

REACT_APP_SENTRY_CLIENT_DSN=<替换为你客户端项目的 DSN>

文档给出的 DSN 形如https://your-server-dsn@sentry.io/your-project-id，其中<...>处替换为你自己在 Sentry 项目 Settings > Client Keys (DSN) 中复制到的实际值。注意客户端 DSN 会随前端代码公开分发给浏览器，服务端机密不要放进.env.client。

验证接入是否生效

文档的验证方式是分别制造一个服务端错误和一个客户端错误，然后在对应的 Sentry 项目中确认错误事件出现。

触发服务端错误

先在main.wasp.ts中声明一个 API（API 的声明方式见 Custom HTTP API Endpoints）：

import { api, app } from "@wasp.sh/spec" import { testError } from "./src/apis" with { type: "ref" } export default app({ // ... spec: [ api("GET", "/testError", 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"); };

启动应用（wasp start）后，在浏览器中直接访问该 API 端点（例如应用地址加上/testError），请求会抛错；此时到 Sentry 的服务端项目中查看，应能看到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> ); };

打开页面并点击 “Test Sentry Error” 按钮，到 Sentry 的客户端项目中查看是否收到对应的错误事件。两侧事件都能收到，说明上报链路已经打通，之后可以删掉这些测试代码。

可选的进阶配置

以下都来自 sentry.md 的 Advanced Configuration 一节，属于可选分支，不影响基本的错误上报。

附加用户信息

在服务端操作（operations）中记录是哪个用户触发了错误：

import * 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, }); } // ... };

调整采样率

默认示例里tracesSampleRate: 1.0是全量采样。文档给出的生产示例是只采集 10%：

Sentry.init({ dsn: "your-dsn", // 替换为你的 DSN tracesSampleRate: 0.1, // Capture 10% of transactions profilesSampleRate: 0.1, // Capture 10% of profiles (if using profiling) });

用 Sentry 的 React 错误边界

import * as Sentry from "@sentry/react"; export const App = ({ children }) => { return ( <Sentry.ErrorBoundary fallback={<p>An error occurred</p>}> {children} </Sentry.ErrorBoundary> ); };

限制与后续

• 该指南在 Wasp 0.24、@sentry/node8、@sentry/react8 下验证过；其他版本的 Sentry SDK 行为可能有差异，文档未给出更多兼容范围说明。
• 服务端与客户端必须分别使用各自项目的 DSN，两个 DSN 混用会导致错误进入错误的项目。
• 更多 Sentry SDK 的配置项（采样、用户上下文等）文档建议直接参考 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