SvelteKit生产构建后根路径首页/无法加载其余页面正常

问题特征 #

• 异常仅在生产构建运行时触发：执行vite dev启动开发服务、vite preview启动预览服务时所有页面均正常访问；执行vite build && node build/启动生产产物时仅根路径/首页无法加载，其余路由访问正常
• 已排除首页组件本身代码问题：将首页内容替换为纯文本Test后生产环境依旧加载失败
• curl请求首页返回初始HTML无明显异常
• 问题首次出现于项目依赖升级、构建命令从旧版svelte-kit build切换为vite build之后

排查步骤与解决方案 #

1. 先定位异常层级 #

先打开浏览器访问首页，按F12调出开发者工具，查看「控制台」和「网络」面板的报错：

• 如果是JS/CSS资源加载404：直接走下面第2点排查
• 如果是响应头非法、跨域、CSP拦截报错：直接走下面第3点排查
• 如果是服务端返回5xx/4xx状态码：直接走下面第4点排查

注：curl仅请求初始HTML文档，不会加载关联资源、不会执行JS、也不会校验响应头合规性，因此会出现curl返回正常但浏览器加载失败的情况，不要以curl结果作为判断依据。

2. 排查静态资源与路由冲突问题 #

这是升级构建命令后最高发的问题：

• 检查项目static/根目录，删除所有遗留的index.html、index.htm等静态首页文件，SvelteKit生产环境下静态文件优先级高于SSR路由，旧的静态首页会直接覆盖路由生成的动态首页，且旧文件内引用的JS/CSS资源路径和新构建产物不匹配，会导致浏览器加载资源失败
• 执行vite build后检查build/client/目录，若根目录存在自动生成的index.html直接删除，这是旧版本构建逻辑的残留文件，会覆盖SSR路由响应
• 检查svelte.config.js中的kit.paths.base配置，确保值为空字符串''，不要误设为/，否则会导致根路径资源引用路径异常。

3. 检查反向代理与服务端响应逻辑 #

如果生产环境Node服务前套了Nginx、CDN等反向代理：

• 先绕过代理，直接通过Node服务监听的端口（默认3000）访问http://127.0.0.1:3000/，如果直接访问正常，说明是代理层规则问题：检查代理层是否对根路径配置了特殊缓存、强制跳转、鉴权、默认页规则，清空代理层缓存后重试
• 检查src/hooks.server.js/ts中的handle逻辑，确认没有针对/路径单独写响应头修改、重定向、cookie写入逻辑，生产环境下响应头如果提前返回、或设置了不合法的字段值，浏览器会直接拦截响应。

4. 检查适配器与路由配置 #

• 确认使用的Node适配器@sveltejs/adapter-node版本与当前SvelteKit、Vite大版本完全对齐，跨大版本升级时适配器API存在不兼容变更，不会抛出显性报错但会出现路由匹配异常
• 检查构建产物中build/server/目录下的路由manifest文件，搜索"/"路由条目，确认根路径路由正常注册，没有被其他路由规则覆盖；如果条目缺失，检查src/routes/下根路径的+page.svelte文件命名是否正确，是否被误加了路由匹配约束、或根级+layout.js/ts存在限制根路径渲染的逻辑。

快速验证方法 #

如果逐点排查效率低，可以按顺序做最小化验证：

1. 临时将适配器换成@sveltejs/adapter-static生成纯静态站点，用本地静态服务启动后访问首页，如果正常说明问题出在adapter-node配置或版本兼容上
2. 临时注释掉所有hooks中的自定义逻辑，删除static目录下所有非必要静态文件，重新构建后测试，如果首页恢复再逐行放开逻辑定位问题点。

内容的提问来源于stack exchange，提问作者Kaiser