Next.js App Router 动态路由 404 响应正确配置指南

本文详解如何在 Next.js app router 中为动态路由（如 /works/[slug]）正确返回 http 404 状态码，避免无效 slug 返回 200 + 空数据，通过 dynamicParams 配置实现服务端级路由守卫。

本文详解如何在 next.js app router 中为动态路由（如 `/works/[slug]`）正确返回 http 404 状态码，避免无效 slug 返回 200 + 空数据，通过 `dynamicparams` 配置实现服务端级路由守卫。

在 Next.js App Router 中，动态路由（如 app/works/[slug]/page.js）默认启用按需生成（dynamicParams: true），这意味着即使某个 slug 在构建时未被预生成（例如未出现在 generateStaticParams 中），请求仍会进入页面组件并返回 200 状态——这与传统服务端路由语义不符，也影响 seo、爬虫行为和错误处理一致性。

要让缺失对应数据的动态路由真正返回 404 HTTP 状态码，关键不是在客户端跳转 /404，而是通过服务端配置提前拦截无效路径。Next.js 提供了 dynamicParams 路由段配置项，它控制着该路由段是否允许“未声明”的动态参数值被访问：

// app/works/[slug]/page.js export const dynamicParams = false;  export default function SingleWork({ params }) {   const { slug } = params;   // 此处逻辑不变：仍可使用 SWR 或 async Server Component 获取数据 }

当 dynamicParams = false 时，Next.js 仅允许 slug 值存在于 generateStaticParams 返回的数组中；否则直接返回 404（HTTP 状态码为 404，且渲染内置或自定义的 not-found.js）。这是服务端行为，无需客户端 JavaScript 参与，性能更优、语义更准确。

因此，完整实践需配合 generateStaticParams 预声明有效 slug：

// app/works/[slug]/page.js export const dynamicParams = false;  export async function generateStaticParams() {   try {     const res = await fetch('http://localhost:1337/api/works?fields[0]=slug');     const works = await res.json();     return works.data.map((work) => ({       slug: work.attributes.slug,     }));   } catch (error) {     console.warn('Failed to fetch static params for works:', error);     return [];   } }  export default async function SingleWork({ params }) {   const { slug } = params;   const res = await fetch(     `http://localhost:1337/api/works?filters[slug][$eq]=${slug}&populate=*`,     { cache: 'no-store' }   );   const data = await res.json();    if (!data.data?.length) {     notFound(); // 触发 404（当 dynamicParams=false 且 generateStaticParams 未覆盖该 slug 时，此行通常不会执行，但作为兜底安全）   }    return (     <div>       <h1>Work: {data.data[0].attributes.title}</h1>       <p>{data.data[0].attributes.description}</p>     </div>   ); }

⚠️ 注意事项：

• dynamicParams: false 仅对 静态生成（SSG）或混合渲染（Hybrid）场景有效；若整个应用启用了 dynamic: ‘force-dynamic’ 或页面内使用 fetch(…, { cache: ‘no-store’ })，则可能绕过静态参数校验，此时需配合 notFound() 显式触发 404。
• generateStaticParams 必须是异步函数，且返回扁平化的参数对象数组（如 { slug: ‘my-work’ }）。
• 若 CMS 数据频繁变更，建议结合 Incremental Static Regeneration (ISR) 设置 revalidate，确保静态参数及时更新。
• 客户端重定向（如 router.push(‘/404’)）仅改变 URL 和 ui，HTTP 状态码仍是 200，不符合 restful 规范，也不利于 SEO —— 应坚决避免。

✅ 总结：
正确处理动态路由 404 的核心是「服务端前置校验」：通过 dynamicParams = false + generateStaticParams 声明合法参数集，使无效路径在路由匹配阶段即被拒绝，返回标准 404 状态。这比客户端空数据判断更健壮、更符合 Web 标准，也是 Next.js App Router 推荐的最佳实践。