SvelteKit 2 项目搭建与开发工作流：以 sentry-javascript 的 sveltekit-2 E2E 测试应用为例

可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载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.8vite为^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 sveltelatest # 在 my-app 目录创建一个新项目 npm create sveltelatest my-appsveltekit-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 可以确认这些命令的实际落点脚本实际执行的命令说明devvite devSvelteKit 2 的 Vite 5 开发服务器buildvite build生产构建previewvite preview本地预览生产构建产物checksvelte-kit sync svelte-check --tsconfig ./tsconfig.json类型检查cleannpx rimraf node_modules pnpm-lock.yaml清理依赖proxynode start-event-proxy.mjs本地事件代理服务器详见后文其中--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. 服务端 hookssrc/hooks.server.tsimport { 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. 客户端 hookssrc/hooks.client.tsimport { 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_ENVproduction playwright test pnpm test:dev # TEST_ENVdevelopment 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两个服务并都配置了 healthcheckmysqladmin ping/redis-cli ping--wait参数确保健康检查通过后才启动测试。MySQL 容器还特别通过--default-authentication-pluginmysql_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为routespan 名使用路由模板/users/[id]而非具体路径服务端 span 的sentry.origin为auto.http.sveltekit客户端与服务端 span 的trace_id一致证明客户端导航与服务端请求被连接为同一条分布式 trace每次重定向都会各自产生一个独立的 navigation trace。八、小结从脚手架到可验证的 Sentry 应用回到 README 的主线一个 SvelteKit 项目的完整生命周期是npm create sveltelatest创建项目 → 安装依赖 →npm run dev可选-- --open开发 →npm run build构建 →npm run preview预览最后根据部署环境选择合适的 adapter。sveltekit-2在这个标准流程之上展示了两个 Sentry 工程实践接入点集中且少只需在vite.config.js中启用sentrySvelteKit插件并在hooks.server.ts/hooks.client.ts中通过Sentry.sentryHandle()、Sentry.handleErrorWithSentry挂载 SDKadapter 决定运行形态E2E 测试选择adapter-node使生产模式可以直接node build启动与开发模式的vite dev形成两条可对比的验证路径。如果你需要在自己的 SvelteKit 2 项目中参考这套配置可直接查看本仓库中的 hooks.server.ts、hooks.client.ts、vite.config.js 与 svelte.config.js 作为对照样本注意其中 DSN 与 tunnel 地址是测试环境专用的实际项目应替换为自己的 Sentry 配置。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐SvelteKit 2 Svelte 5 组合下的 Sentry E2E 测试应用sentry-javascript 如何验证 sentry/sveltekit SDKSvelteKit 2 Svelte 5 组合下的 Sentry E2E 测试应用sentry javascript 如何验证 sentry/svelt可观测性sentry-javascript SvelteKit 2 Tracing E2E 测试应用基于 create-svelte 的搭建、构建与 Tracing 验证指南sentry javascript SvelteKit 2 Tracing E2E 测试应用基于 create svelte 的搭建、构建与 Tracing可观测性Sentry SolidStart SDK E2E 测试应用解析以 solidstart-spa 为例搭建 SPA 模式 Solid 项目并验证错误与性能上报Sentry SolidStart SDK E2E 测试应用解析以 solidstart spa 为例搭建 SPA 模式 Solid 项目并验证错误与性能上报可观测性上一篇终极指南如何用qmcdump一键解码QQ音乐加密音频文件下一篇如何轻松掌握猫抓视频嗅探新手也能快速上手的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考