Nuxt3部署Cloudflare Pages报错.output/public目录不存在问题排查

问题现象 #

本地可正常编译Nuxt3项目，部署到Cloudflare Pages时构建失败，构建日志显示.output/public目录已生成，但最终校验阶段抛出错误导致部署中断，完整构建日志如下：

00:14:35.140    Executing user command: npm run generate
00:14:35.613    
00:14:35.613    > generate
00:14:35.613    > nuxt generate
00:14:35.614    
00:14:35.725    Nuxt CLI v3.0.0-rc.3-27567768.c1f728e
00:14:38.919    ✔ Using ~/components/content for components in Markdown
00:14:43.437    ℹ Vite client warmed up in 3072ms
00:14:44.646    ℹ Client built in 4280ms
00:14:44.681    ℹ Building server...
00:14:47.053    ✔ Server built in 2373ms
00:14:47.249    ✔ Generated public dist
00:14:47.249    ℹ Initializing prerenderer
00:14:50.871    ℹ Prerendering 4 initial routes with crawler
00:14:50.891      ├─ / (20ms) 
00:14:50.894      ├─ /200 (3ms) 
00:14:50.897      ├─ /404 (3ms) 
00:14:50.958      ├─ /api/_content/cache (61ms) 
00:14:50.971    ✔ You can now deploy .output/public to any static hosting!
00:14:51.017    Finished
00:14:51.018    Note: No functions dir at /functions found. Skipping.
00:14:51.018    Validating asset output directory
00:14:51.018    Error: Output directory ".output/public" not found.
00:14:52.095    Failed: build output directory not found

构建报错截图：

解决步骤 #

• 修改Cloudflare Pages输出目录配置：你当前使用的Nuxt 3.0.0 RC3版本存在构建日志提示和实际输出路径不一致的问题，该版本执行nuxt generate时，静态产物实际输出到项目根目录的dist文件夹，并不会生成.output/public目录。直接在Cloudflare Pages项目的构建设置中，将「输出目录」字段的值从.output/public改为dist，保存后重新触发构建即可通过目录校验。
• 显式指定产物输出路径：如果需要统一使用.output/public作为输出目录，在项目根目录的nuxt.config.ts中添加如下配置，强制Nitro构建模块将静态文件输出到指定路径：

export default defineNuxtConfig({
  nitro: {
    output: {
      publicDir: '.output/public'
    }
  }
})

• 检查文件忽略规则：打开项目根目录的.gitignore文件，确认没有将.output目录加入忽略列表。Cloudflare Pages构建流程会自动过滤被git标记为忽略的文件和目录，即使构建阶段生成了对应目录，后续校验环节也无法读取到目录内容，移除相关忽略规则后重新部署即可。
• 升级Nuxt到正式稳定版：当前使用的RC预览版存在大量构建逻辑不稳定、路径输出不符合预期的已知问题，升级到Nuxt 3正式稳定版后，nuxt generate的产物输出路径会和官方日志提示完全一致，不会出现路径不匹配的问题。

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