Next.js静态路径本地正常，Azure部署后返回404问题排查

问题场景 #

在Azure免费静态Web应用托管计划中，部署了采用Next.js getStaticPaths 和 getStaticProps 预渲染的Web应用。本地运行一切正常，但部署后，/menu/rice、/menu/okele等动态路由页面返回404错误，而/contact、/more/faqs等静态路径可正常访问。

相关代码与日志 #

动态路由页面代码 #

export async function getStaticPaths() {
    return {
        paths: [
            { params: { id: 'rice' } },
            { params: { id: 'okele' } },
            // 更多路径...
            { params: { id: 'beers' } }
        ],
        fallback: false
    };
}

export async function getStaticProps({ params }) {
    const menuData = await API.fetchMenu();
    const categoryData = menuData.Categories.find(item => item.CategoryName.toLowerCase() === params.id);

    return {
        props: {
            category: categoryData,
        },
        revalidate: 3600  // ISR 增量静态再生
    };
}

Azure构建日志（显示页面已生成） #

├ ● /menu/[id] (ISR: 3600 Seconds) (2532 ms)
├   ├ /menu/rice (592 ms)
├   ├ /menu/okele
├   └ [+5 more paths]

尝试的配置更新（无效） #

添加了staticwebapp.config.json，但动态路由仍无法访问：

{
  "routes": [
    {
      "route": "/menu/*",
      "serve": "/menu/[id].html",
      "statusCode": 200
    }
  ]
}

核心问题 #

1. 为何本地正常、构建日志显示页面生成成功，Azure部署后却返回404？
2. 该问题是否与Azure的静态路径处理逻辑或Next.js在Azure上的特定配置要求有关？
3. Azure平台上Next.js动态路由是否存在已知问题或通用解决方法？

解答与解决方案 #

1. 404错误原因 #

Azure静态Web应用默认按请求路径直接查找对应静态文件，但Next.js构建动态路由时，会生成out/menu/rice.html这类具体文件，而非/menu/[id].html。你之前的staticwebapp.config.json规则指向的是未实际生成的[id].html，无法匹配到真实存在的静态文件，导致404。另外，Azure对ISR模式下的路由匹配需要明确的重写规则，默认规则无法自动解析Next.js的动态路由输出结构。

2. 与Azure配置的关联 #

是的，问题直接关联Azure的路由规则配置。Next.js的静态输出结构和Azure默认的静态文件查找逻辑不匹配，必须通过staticwebapp.config.json配置适配的路由重写规则，才能让Azure正确映射动态路由请求到对应的静态文件。

3. 解决方法 #

方法一：修正staticwebapp.config.json路由规则

将路由规则改为重写请求到实际生成的静态文件：

{
  "routes": [
    {
      "route": "/menu/*",
      "rewrite": "/menu/$1.html"
    }
  ]
}

该规则会将/menu/rice这类请求重写为/menu/rice.html，直接匹配Next.js构建生成的静态文件。

方法二：验证Next.js构建输出结构

检查本地out目录下是否存在/menu/rice.html、/menu/okele.html等文件。如果文件缺失，说明getStaticPaths或getStaticProps逻辑存在问题，需排查数据获取或路径生成代码是否正确。

方法三：调整Next.js的fallback配置（可选）

若后续会新增动态路径，可将fallback设为'blocking'，当访问未预渲染的路径时，Next.js会在服务器端临时生成页面并缓存。注意：Azure免费计划对服务器端渲染的资源有限制，需确认是否符合计划要求。

方法四：确认Azure构建命令正确性

确保Azure使用的构建命令为Next.js标准静态导出命令：

npm run build && npm run export

若使用Next.js 13+ App Router，需确认构建输出格式兼容Azure静态Web应用的托管模式。

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