企业官网建设流程全解析

• 可观测性

dev-packages/e2e-tests/test-applications/sveltekit-2是 sentry-javascript 仓库中用于端到端验证@sentry/sveltekit包的测试应用，它完全基于 SvelteKit 2 + Vite 5 的标准脚手架搭建。本文以该应用的 README 为主线，讲解从创建 SvelteKit 项目、启动开发服务器到生产构建的完整工作流，并结合仓库中真实的配置文件与测试代码，展示一个 SvelteKit 项目是如何接入 Sentry 埋点并被 E2E 测试驱动的。读完本文，你可以掌握 SvelteKit 项目的标准开发命令、adapter 机制的作用，以及 Sentry 在 SvelteKit 中的接入位置与验证方式。

一、项目定位：一个标准的 SvelteKit 2 脚手架应用

sveltekit-2 的 README 开头即说明：这个项目由create-svelte脚手架生成，"包含了构建 Svelte 项目所需的一切"。从 package.json 可以看到它的技术栈版本：

• @sveltejs/kit固定为2.60.1（这也是目录名sveltekit-2的由来——它代表 SvelteKit 2.x 主线的测试基线）；
• svelte为^4.2.8，vite为^5.4.11；
• 依赖了@sentry/sveltekit（以本地打包产物file:../../packed/sentry-sveltekit-packed.tgz的形式引入，保证测试的是本次构建出来的 SDK 版本）；
• 额外依赖mysql与ioredis两个数据库驱动，用于数据库集成的 E2E 测试（注释中特别说明ioredis锁定在5.10.1，因为这是该驱动最后一个尚未支持 tracing channels 的版本）。

也就是说，这个目录虽然表面上是一个普通的 SvelteKit 应用，但在仓库中它的实际角色是：作为被测对象，持续验证@sentry/sveltekit的错误捕获、性能追踪与数据库集成能力。

二、创建 SvelteKit 项目

README 中给出的创建命令如下，适用于从零开始初始化一个新项目（在当前目录或指定目录）：

# 在当前目录创建一个新项目 npm create svelte@latest # 在 my-app 目录创建一个新项目 npm create svelte@latest my-app

sveltekit-2本身正是这样生成的（README 中的原话是"如果你能看到这段话，说明你大概率已经完成了这一步"）。创建完成后，需要安装依赖：npm install、pnpm install或yarn任选其一即可。仓库中该应用的volta字段继承了dev-packages/package.json的 Node 版本约束，实际开发中以仓库推荐的 Node 版本为准。

三、启动开发服务器

安装依赖后，README 给出的开发模式启动命令是：

npm run dev # 或者启动服务器并自动在浏览器新标签页打开应用 npm run dev -- --open

对照 package.json 中的 scripts 可以确认这些命令的实际落点：

其中--open是透传给vite dev的参数，Vite 会尝试用系统默认浏览器打开开发服务器地址。

值得注意的细节：SvelteKit 项目的 Vite 配置必须加载sveltekit()插件，本应用的 vite.config.js 在sveltekit()之前还挂载了 Sentry 的 Vite 插件：

import { sentrySvelteKit } from '@sentry/sveltekit/vite'; import { sveltekit } from '@sveltejs/kit/vite'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [ sentrySvelteKit({ autoUploadSourceMaps: false, }), sveltekit(), ], });

sentrySvelteKit插件负责在开发/构建时收集并处理 source map（测试中关闭了自动上传），而sveltekit()插件提供路由与构建的核心能力，两者缺一不可。

四、生产构建与预览

README 给出的构建命令：

npm run build

构建完成后可以用npm run preview在本地预览生产产物。

README 中还有一个关键提示：部署应用时，可能需要为部署目标环境安装对应的 adapter。这一点在仓库中得到了直接印证——svelte.config.js 中显式选择了 Node 平台的 adapter，因为 E2E 测试需要把构建产物作为独立 Node 进程运行：

import adapter from '@sveltejs/adapter-node'; import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'; const config = { preprocess: vitePreprocess(), kit: { adapter: adapter(), }, }; export default config;

@sveltejs/adapter-node会把应用打包为可直接node build启动的 Node 服务，这正是后文 E2E 测试在 production 模式下拉起应用所依赖的形态。adapter 决定了产物形态（Node 服务、静态站点、特定云函数等），选择它时应以最终部署目标为准。

五、Sentry 在 SvelteKit 中的接入点（源码佐证）

作为 Sentry 的 E2E 测试应用，sveltekit-2展示了@sentry/sveltekit的两个标准接入位置，这也是 README 所述"开发/构建"流程中 SDK 真正发挥作用的地方：

1. 服务端 hooks：src/hooks.server.ts

import { E2E_TEST_DSN } from '$env/static/private'; import * as Sentry from '@sentry/sveltekit'; Sentry.init({ environment: 'qa', // 动态采样偏向，用于保留 transaction dsn: E2E_TEST_DSN, debug: !!process.env.DEBUG, tunnel: 'http://localhost:3031/', // 代理服务器 tracesSampleRate: 1.0, }); // 不向 console 输出，避免污染测试日志 export const handleError = Sentry.handleErrorWithSentry(() => {}); export const handle = Sentry.sentryHandle();

这里handle由Sentry.sentryHandle()生成，是 SvelteKit 请求生命周期中的 instrumentation hook，负责服务端 span 与 trace 传播；handleError用Sentry.handleErrorWithSentry包装，把未处理错误上报给 Sentry。tunnel指向本地事件代理（npm run proxy启动的start-event-proxy.mjs），用于拦截并校验 SDK 发出的事件。

2. 客户端 hooks：src/hooks.client.ts

import { env } from '$env/dynamic/public'; import * as Sentry from '@sentry/sveltekit'; Sentry.init({ environment: 'qa', dsn: env.PUBLIC_E2E_TEST_DSN, debug: !!env.PUBLIC_DEBUG, tunnel: 'http://localhost:3031/', tracesSampleRate: 1.0, }); const myErrorHandler = ({ error, event }: any) => { console.error('An error occurred on the client side:', error, event); }; export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);

客户端侧同样通过 SvelteKit 的handleError导出挂载错误上报，DSN 通过$env/dynamic/public注入（客户端可见），与服务端的$env/static/private区分开——这是 SvelteKit 环境变量按运行环境隔离的典型用法。

六、E2E 测试如何驱动这个应用（dev 与 prod 双环境）

README 描述的"dev/build/preview"三种运行形态，在 playwright.config.mjs 中被直接复用为两种测试环境：

import { getPlaywrightConfig } from '@sentry-internal/test-utils'; const testEnv = process.env.TEST_ENV; if (!testEnv) { throw new Error('No test env defined'); } const config = getPlaywrightConfig({ startCommand: testEnv === 'development' ? 'pnpm dev --port 3030' : 'node build', }); export default { ...config, globalSetup: './global-setup.mjs', globalTeardown: './global-teardown.mjs', };

• development 模式：pnpm dev --port 3030，即上文npm run dev对应的 Vite 开发服务器；
• production 模式：node build，直接运行 adapter-node 产出的构建产物——这也解释了为什么第四节的 adapter 选择如此重要。

package.json 中的测试脚本与之一一对应：

pnpm test:prod # TEST_ENV=production playwright test pnpm test:dev # TEST_ENV=development playwright test db（开发模式下只跑 db 套件） pnpm test:build # pnpm install && pnpm build pnpm test:assert # 先跑生产断言再跑开发断言

数据库依赖由 Docker Compose 自动拉起：global-setup.mjs 在测试前执行docker compose up -d --wait，而 docker-compose.yml 定义了mysql:8.0与redis:7两个服务，并都配置了 healthcheck（mysqladmin ping/redis-cli ping），--wait参数确保健康检查通过后才启动测试。MySQL 容器还特别通过--default-authentication-plugin=mysql_native_password强制使用旧版认证插件——因为应用依赖的mysql2.x 驱动不支持 MySQL 8 默认的caching_sha2_password认证。

七、被测路由与测试覆盖概览

从 src/routes 目录结构可以看到，应用的路由就是测试用例的"靶子"：

• users/[id]、users：带参数路由与服务端 load，用于验证分页负载（pageload）的分布式 trace 连接；
• server-load-error、server-route-error、client-error、universal-load-error：各类错误场景，供 errors.server.test.ts 与 errors.client.test.ts 断言；
• db-ioredis、db-mysql：对应 docker-compose 拉起的两类数据库，由 db.test.ts 验证 SDK 的数据库集成；
• redirect1、redirect2、nav1、nav2：导航与重定向链路，验证 navigation span 的正确性。

以 tests/performance.test.ts 为例，测试通过@sentry-internal/test-utils提供的collectStreamedSpans收集经代理服务器流式转发的 span，并断言：

• 客户端 pageload segment 的sentry.op为pageload、sentry.origin为auto.pageload.sveltekit，且sentry.segment.name.source为route（span 名使用路由模板/users/[id]而非具体路径）；
• 服务端 span 的sentry.origin为auto.http.sveltekit；
• 客户端与服务端 span 的trace_id一致，证明客户端导航与服务端请求被连接为同一条分布式 trace；
• 每次重定向都会各自产生一个独立的 navigation trace。

八、小结：从脚手架到可验证的 Sentry 应用

回到 README 的主线，一个 SvelteKit 项目的完整生命周期是：npm create svelte@latest创建项目 → 安装依赖 →npm run dev（可选-- --open）开发 →npm run build构建 →npm run preview预览，最后根据部署环境选择合适的 adapter。sveltekit-2在这个标准流程之上展示了两个 Sentry 工程实践：

1. 接入点集中且少：只需在vite.config.js中启用sentrySvelteKit插件，并在hooks.server.ts/hooks.client.ts中通过Sentry.sentryHandle()、Sentry.handleErrorWithSentry挂载 SDK；
2. adapter 决定运行形态：E2E 测试选择adapter-node，使生产模式可以直接node build启动，与开发模式的vite dev形成两条可对比的验证路径。

如果你需要在自己的 SvelteKit 2 项目中参考这套配置，可直接查看本仓库中的 hooks.server.ts、hooks.client.ts、vite.config.js 与 svelte.config.js 作为对照样本（注意其中 DSN 与 tunnel 地址是测试环境专用的，实际项目应替换为自己的 Sentry 配置）。

• 可观测性