使用Turborepo部署SvelteKit到Vercel时全缓存命中触发404问题

问题背景 #

• 环境：基于Turborepo管理的多SvelteKit Web应用仓库，已启用Turborepo缓存功能，部署平台为Vercel
• 异常场景1：当仓库非应用代码变更触发某应用部署，且Turborepo缓存100%命中时，访问应用出现404页面；开启目录列表后可看到对应目录内容
• 正常场景：若部署由应用自身代码变更触发（无缓存命中），部署后应用访问完全正常
• 更新1：移除Vercel部署配置中的Output Directory覆盖，恢复为默认public后，全缓存命中的部署会直接触发部署错误

可能原因与解决方案 #

1. Turborepo缓存与SvelteKit构建产物适配性问题 #

Turborepo缓存复用的旧构建产物，未包含当前部署所需的环境变量、Vercel路由适配逻辑等动态内容，导致产物无法被Vercel正确识别。

• 解决方案：在turbo.json的构建任务中添加环境变量哈希依赖，确保环境变化时缓存自动失效：

  {
    "pipeline": {
      "build": {
        "dependsOn": ["^build"],
        "outputs": [".svelte-kit/**", "public/**"],
        "env": ["VERCEL_ENV", "VERCEL_URL"]
      }
    }
  }
  

• 同时检查SvelteKit配置文件（vite.config.ts/svelte.config.js），确保构建逻辑未被缓存产物干扰，必要时添加强制刷新构建缓存的逻辑。

2. 构建产物路径与Vercel配置不匹配 #

自定义Output Directory时，缓存产物路径与Vercel期望的入口路径不一致；恢复默认public后，缓存产物缺失SvelteKit部署必需的.svelte-kit目录内容，导致部署失败。

• 解决方案：
  • 移除Vercel的Output Directory自定义配置，依赖SvelteKit框架自动适配Vercel的部署路径要求
  • 在turbo.json中明确指定构建任务需缓存的完整产物目录：

    {
      "pipeline": {
        "build": {
          "outputs": [".svelte-kit/**", "public/**", "package.json"]
        }
      }
    }
    

3. 临时验证方案：强制跳过缓存 #

在Vercel部署环境变量中添加TURBO_FORCE=1，强制Turborepo执行全量构建、跳过缓存验证，确认异常是否由缓存直接导致。

验证步骤 #

1. 修改Turborepo配置后，提交根目录README等非应用代码变更，触发跨应用部署，检查缓存命中时的访问状态
2. 对比缓存命中与正常构建的Vercel部署日志，确认产物路径、文件完整性是否一致
3. 检查应用的package.json中build脚本，确保执行的是标准svelte-kit build命令，而非仅生成public目录的自定义脚本

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