Next.js部署到Vercel后出现404错误，求助排查方案

1. 检查页面文件结构与命名 #

• 确认pages目录下存在正确命名的首页文件：index.js/index.tsx（Pages Router）或app/page.js/app/page.tsx（App Router）。部署环境（Linux）对文件名大小写敏感，若本地是Windows，注意不要出现Index.js这类大写开头的文件，否则Vercel无法识别为首页。
• 检查首页文件是否存在语法错误或逻辑错误，比如在getStaticProps/getServerSideProps中抛出未捕获的异常，导致页面构建失败，最终 fallback 到404页面。

2. 修复样式丢失问题 #

• 全局样式文件（如styles/globals.css）必须在_app.js/_app.tsx（Pages Router）或根layout.js（App Router）中正确导入，示例：

  // Pages Router: _app.js
  import '../styles/globals.css'
  
  function MyApp({ Component, pageProps }) {
    return <Component {...pageProps} />
  }
  
  export default MyApp
  

• 检查样式文件的相对路径是否正确，避免因路径层级错误导致部署时无法加载样式资源。
• 若使用CSS Modules，确保文件名遵循[name].module.css格式，导入时正确使用模块化语法。

3. 核对构建与部署配置 #

• 打开next.config.js，确认未错误设置basePath或assetPrefix，这两个配置会影响资源和页面的路由路径，若部署时未对应配置会导致资源加载失败和页面404。
• 在Vercel项目设置中，确认Framework Preset为Next.js，Build Command为next build，Output Directory为.next，这些是Next.js部署的默认配置，若被修改会导致异常。
• 查看Vercel部署日志，搜索是否有构建警告或错误（比如依赖缺失、页面构建失败），即使控制台显示“部署成功”，部分隐性错误也会导致首页无法正常生成。

4. 排查环境变量的影响 #

• 检查首页组件或数据获取函数中是否依赖环境变量，若变量未正确配置，可能导致数据获取失败，进而页面无法渲染。比如：

  // getStaticProps示例
  export async function getStaticProps() {
    const apiUrl = process.env.NEXT_PUBLIC_API_URL
    // 若apiUrl未正确设置，会导致请求失败
    const res = await fetch(apiUrl)
    const data = await res.json()
    return { props: { data } }
  }
  

• 确保Vercel项目设置中添加的环境变量与代码中的变量名完全一致，客户端变量需以NEXT_PUBLIC_开头，否则无法在浏览器中访问。

5. 其他排查技巧 #

• 在本地执行next build && next start，模拟生产环境运行，若能复现问题，说明是代码或构建配置问题，而非Vercel平台问题，可在本地调试解决。
• 在Vercel中重新部署，勾选清除构建缓存选项，避免旧缓存导致的异常。
• 检查是否存在自定义404.js页面，确认首页逻辑中没有错误触发404渲染的情况（比如错误判断数据存在性）。

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