部署Next.js v12到AWS Amplify遇404错误排查咨询

1. 部署配置与构建产物校验 #

• 确认 Amplify 构建配置的baseDirectory适配性：本地执行npm run buildamp后，检查.next目录下是否存在server、static、pages等核心子目录，确保构建产物完整。若缺失关键目录，说明构建过程存在隐性错误（即使命令未报错）。
• 检查 Amplify 控制台框架设置：确认已选择Next.js作为部署框架，而非通用静态网站类型——Amplify 对 Next.js SSR 有专门的路由处理逻辑，选错类型会直接导致路由不匹配。

2. Next.js 路由与配置检查 #

• 核对next.config.js的路由相关配置：比如trailingSlash选项，若 Amplify 静态托管默认要求尾斜杠（或反之），两者不一致会导致路由失效。可尝试切换trailingSlash: true或false后重新部署验证。
• 检查页面文件的命名与路径：确认根目录下的pages目录存在，且首页文件（index.js/ts）、其他页面文件无大小写拼写错误（Linux 环境区分大小写，本地 Windows 可能忽略）。
• 排查自定义路由规则：若next.config.js中有rewrites、redirects配置，需确认这些规则在 Amplify 环境下是否生效，避免规则冲突导致请求无法到达对应页面。

3. TS/JS 配置文件问题 #

• 校验tsconfig.json/jsconfig.json的路径别名：若配置了baseUrl和paths，需确保next.config.js中同步配置了resolve.alias，否则构建时路径解析错误会导致页面组件未被正确打包。
• 检查配置文件的语法与兼容性：执行tsc --noEmit（TS 项目）检查是否有类型错误或配置语法问题，避免因配置不兼容 Next.js v12 导致页面未生成。

4. Amplify 重写与重定向规则 #

• 进入 Amplify 控制台的「Rewrites and redirects」页面，确认存在 Next.js 所需的默认规则：

  </^[^.]+$|\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|ttf|map|json)$)([^.]+$)/> /index.html 200
  

  这条规则会将所有非静态资源请求指向index.html，交由 Next.js 处理路由，缺失该规则会直接导致 404。
• 排查自定义重定向规则：若添加过自定义规则，确认未覆盖默认的 Next.js 路由规则，避免请求被错误重定向。

5. 构建日志的隐性错误 #

• 仔细查看 Amplify 构建日志的全量输出，尤其是build阶段：即使构建检查项显示成功，也可能存在页面组件编译警告或隐性错误（如 TypeScript 类型未严格校验导致页面未生成）。
• 检查preBuild阶段的npm ci输出：确认依赖安装完全成功，无缺失或版本不兼容的情况，依赖问题可能导致页面构建失败但不终止整个构建流程。

6. 环境变量配置 #

• 确认 Amplify 控制台配置的环境变量与本地一致：若项目依赖环境变量（如 API 地址、密钥），部署时缺失会导致动态路由或页面渲染失败，甚至构建时无法生成对应页面。
• 检查next.config.js中依赖环境变量的配置（如env、publicRuntimeConfig），确认这些配置在 Amplify 环境下已正确加载。

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