SvelteKit 服务器专属模块守卫修复：项目位于 `server` 目录时不再误判所有模块

• Web框架
• 后端
• 前端

导读

SvelteKit 提供了"服务器专属模块"（server-only modules）机制，用于防止后端敏感代码（如环境变量、数据库凭据）被意外带入浏览器端代码。官方文档 50-server-only-modules.md 中明确定义了两种标识服务器专属模块的方式。本篇文章围绕@sveltejs/kit的补丁级变更展开：当整个项目恰好被放置在名为server的目录中时，此前版本会把项目内几乎所有模块误判为服务器专属，导致构建与导入守卫（import guard）行为异常；本次修复让路径判定只关注项目根目录内的部分，从根源上消除了这一误判。读完本文，你将掌握 SvelteKit 服务器专属模块的完整判定规则、导入守卫的底层实现原理，以及本次修复的具体代码逻辑与测试验证。

一、本次变更的背景：一个补丁级的正确性修复

在.changeset/目录下，本次变更以 changeset 文件的形式记录，内容如下（见 calm-roots-guard.md）：

--- '@sveltejs/kit': patch --- fix: don't treat every module as server-only when the project is inside a `server` directory

该变更对@sveltejs/kit属于patch（补丁）级别，即不引入新功能、不破坏现有 API，只修复一处行为错误。它针对的场景是：项目的根目录本身位于一个名为server的目录下（例如仓库路径为/repo/server/），此时旧的路径匹配逻辑会对项目内的几乎所有文件误判为服务器专属模块，从而触发错误的"非法导入"报错，甚至影响构建产物的正确性。

二、SvelteKit 的服务器专属模块：判定规则回顾

要理解本次修复，先回顾官方文档 50-server-only-modules.md 定义的判定规则。

2.1 两种标记方式

根据文档，让一个模块成为服务器专属有两种方式：

1. 在文件名中加入server段，例如server.js或secrets.server.ts，这种方式对项目目录下的任意文件都生效；
2. 将文件放入server目录，该目录可位于项目内任意位置，但不能放在src/routes或static目录内，例如src/lib/server/config.js或src/lib/data/server/user/profile.js。

注：SvelteKit 2 中server目录仅在src/lib文件夹内被识别，这是旧版限制（文档中的 LEGACY 标记）。

2.2 判定边界：工作目录与 node_modules 不受约束

文档同时明确：工作目录之外以及node_modules内的模块（如来自 npm 的包）不受这些规则约束。如果要在发布的 npm 包中提供服务器专属模块，需要在文件顶部显式添加import '$app/server'。

三、底层实现：路径模式与导入守卫

3.1 两条核心路径模式

服务器专属模块的路径判定实现在 packages/kit/src/exports/vite/utils.js：

export const server_only_module_pattern = /[/.]server\.[^/]+$/; export const server_only_directory_pattern = /\/server\//;

• server_only_module_pattern：匹配文件名中含server.段（如module.server.ts）或以/server.结尾路径的模块；
• server_only_directory_pattern：匹配路径中任意位置出现/server/段的目录。

3.2 导入守卫插件的职责

vite-plugin-sveltekit-guard插件（guard.js）负责在构建与开发模式下，防止客户端代码意外导入服务器专属代码。其工作机制是：

1. 构建模块导入图：通过resolveId钩子在enforce: 'pre'阶段运行，收集每个模块的被导入关系（见 guard.js）；
2. 识别服务器专属模块：在load钩子中，对匹配$app/server、$app/env/private、server_only_module_pattern、server_only_directory_pattern的模块进行判定（见 guard.js）；
3. 回溯导入链：从服务器专属模块出发，向上回溯导入关系，若找到一条通向客户端入口点（页面组件、+layout、hooks、service worker 等）的链路，则判定为非法导入并抛出server_only_import错误（见 guard.js）。

官方文档中的报错示例与此实现完全对应：

Cannot import #lib/server/secrets.ts into code that runs in the browser, as this could leak sensitive information. src/routes/+page.svelte imports src/routes/utils.js imports #lib/server/secrets.ts If you're only using the import as a type, change it to `import type`.

即使公开代码只使用了非敏感导出（如文档中的add），只要导入链中触及服务器专属模块，整个链路即被判定为不安全。该机制对动态导入同样生效，包括await import(./${foo}.js)这类插值导入。此外，单元测试框架（如 Vitest）不区分服务器专属与公开代码，因此当process.env.TEST === 'true'时非法导入检测会被禁用。

四、本次修复：只判定项目根目录内的路径

4.1 修复前的缺陷

修复前的is_server_only_path逻辑会直接对模块的完整路径进行正则匹配。当项目本身位于server目录下（如/repo/server/），路径中的/server/段会命中server_only_directory_pattern，于是项目内的几乎所有文件（如/repo/server/src/lib/db.js）都被误判为服务器专属模块。这会导致：

• 合法的客户端代码被错误地判定为"导入服务器专属代码"，触发误报错误；
• 构建与守卫逻辑产生错误行为，影响开发体验。

4.2 修复后的逻辑

修复后的is_server_only_path只检查项目根目录以内的路径部分（见 packages/kit/src/exports/vite/utils.js）：

export function is_server_only_path(id, { root, node_modules, routes, assets }) { if (!id.startsWith(root + '/') || id.startsWith(node_modules + '/')) return false; const relative = id.slice(root.length); return ( server_only_module_pattern.test(relative) || (server_only_directory_pattern.test(relative) && !id.startsWith(routes + '/') && !id.startsWith(assets + '/')) ); }

核心变化有三点：

1. 裁剪相对路径：先通过id.slice(root.length)去掉项目根目录前缀，只对剩余部分做模式匹配，因此根目录外部的server段不再影响判定；
2. 排除根外模块：id.startsWith(root + '/')保证了只处理项目内的模块，根目录之外的文件直接返回false；
3. 保留原有豁免：server目录模式在src/routes与static（assets）目录内不生效，这与文档规则一致。

4.3 判定优先级汇总

修复后完整的服务器专属模块判定逻辑为：

五、测试验证：边界场景全覆盖

本次修复配套的单元测试位于 packages/kit/src/exports/vite/utils.spec.js，其中专门覆盖了"项目本身位于server目录"的场景：

test('only checks the part of the path inside the project root for server-only modules', () => { const check = (id, root) => is_server_only_path(id, { root, node_modules: `${root}/node_modules`, routes: `${root}/src/routes`, assets: `${root}/static` }); expect(check('/app/src/lib/server/db.js', '/app')).toBe(true); expect(check('/app/src/lib/db.server.js', '/app')).toBe(true); expect(check('/app/server/db.js', '/app')).toBe(true); expect(check('/app/src/lib/db.js', '/app')).toBe(false); expect(check('/app/src/routes/server/+page.svelte', '/app')).toBe(false); expect(check('/app/static/server/file.js', '/app')).toBe(false); expect(check('/app/node_modules/pkg/server/index.js', '/app')).toBe(false); expect(check('/outside/server/db.js', '/app')).toBe(false); // the project itself is inside a `server` directory expect(check('/repo/server/.svelte-kit/generated/build/app-manifest.js', '/repo/server')).toBe(false); expect(check('/repo/server/src/lib/db.js', '/repo/server')).toBe(false); expect(check('/repo/server/src/lib/server/db.js', '/repo/server')).toBe(true); expect(check('/repo/server/src/lib/db.server.js', '/repo/server')).toBe(true); });

测试明确断言：当项目根为/repo/server/时，/repo/server/src/lib/db.js不再被误判为服务器专属（返回false），而server目录与server.文件名的真正服务器专属模块仍能正确识别（返回true）。同时测试还验证了server_only_module_pattern的边界，如module.serverish.js不会被误匹配，而module.server.test.js、server.test.ts均会被识别（见 utils.spec.js）。

六、实际影响与升级建议

本次修复对普通开发者最直接的影响是：如果你将 SvelteKit 项目放置在一个名为server的目录下（例如 monorepo 中apps/server/这类布局），升级后构建时不再出现由路径误判引发的伪"非法导入"错误。

对于 monorepo 使用者，需要注意：工作区中其他目录（如packages/、apps/client/）即使路径含server段，只要位于项目根目录之外，就不会参与判定；反之，项目根目录之内src/lib/server/等真正的服务器专属目录行为完全不变。

升级方式：将@sveltejs/kit升级到包含该补丁的版本即可。该变更由 changeset 机制管理（配置见 .changeset/config.json），会在发布时自动合并进 CHANGELOG，无需手动迁移代码；项目中已有的服务器专属模块写法（*.server.js命名与server目录）均不受影响。

延伸阅读

• 官方文档：SvelteKit 服务器专属模块
• 核心实现：路径判定工具、导入守卫插件
• 测试验证：路径判定单元测试
• 变更记录：calm-roots-guard.md

• Web框架
• 后端
• 前端