Nuxt3静态部署Cloudflare时.well-known路由404如何解决

问题现象 #

• 采用Cloudflare作为静态托管服务，执行npx nuxt generate命令部署项目后，访问/.well-known/apple-developer-merchantid-domain-association路由始终返回404错误
• 已尝试两种方案均未生效：
  • 将对应目录与文件直接放入public目录
  • 将验证文件内容注册为服务端路由，同时搭配Nitro预渲染配置声明路由
• 本地使用miniflare模拟生产环境时，依次执行npx nuxt build与npx nuxt preview命令后可正常访问该路由
• 构建产物中/.output/public/_nuxt/entry-[hash].mjs文件并未像处理其他静态资源、页面路由一样注册该.well-known路径

当前使用的配置 #

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt'

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
    
    nitro: {
        preset: 'cloudflare',
        prerender: {
            routes: ['/.well-known/apple-developer-merchantid-domain-association']
        }
    },
    ssr: false,
    target: 'static'
})

/server/routes/.well-known/apple-developer-merchantid-domain-association.ts

import { defineEventHandler } from 'h3'

export default defineEventHandler(() => "92324FSD2FFADAD124RTSDGSDF7B227073704964223A22")

解决方法 #

方案1：静态文件直放（兼容性最好） #

1. 删除之前写的对应服务端路由文件，移除nuxt.config.ts中nitro.prerender里针对该路径的配置，避免路由冲突
2. 在项目public目录下新建.well-known文件夹，将苹果商户验证文件直接放入该目录，文件严格命名为apple-developer-merchantid-domain-association，不要加任何后缀
3. 执行npx nuxt generate后，先检查本地.output/public目录下是否存在.well-known/apple-developer-merchantid-domain-association文件，确认存在再部署
4. Cloudflare Pages部署时，手动将构建输出目录指定为.output/public，不要使用自动识别，避免点开头的隐藏目录被过滤

方案2：路由返回内容（无实体文件场景） #

如果需要通过服务端路由直接返回验证字符串，调整nuxt.config.ts配置，补充路由规则强制该路径预渲染为静态文件：

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
    nitro: {
        preset: 'cloudflare',
        prerender: {
            routes: ['/.well-known/apple-developer-merchantid-domain-association']
        },
        routeRules: {
            '/.well-known/**': {
                headers: {
                    'content-type': 'text/plain'
                }
            }
        }
    },
    ssr: false,
    target: 'static'
})

该方案同样需要在Cloudflare Pages中手动指定构建输出目录为.output/public，部署后可在Pages的部署详情-文件列表中确认.well-known路径下的文件已被正确上传。

内容的提问来源于stack exchange，提问作者A.Morris