通过GitHub Actions+Netlify CLI部署Next.js网站遇404问题求助

核心原因 #

你手动在GitHub Actions中执行npm run build后直接上传.next目录，导致@netlify/plugin-nextjs未被触发运行。这个插件是Netlify适配Next.js路由、生成必要服务端函数的关键，缺少它的处理，Netlify无法正确解析Next.js的页面路由，自然会返回404。

具体修复步骤 #

1. 修改GitHub Actions配置（production.yml） #

移除单独的Build步骤，让Netlify CLI全权处理构建和部署，确保插件能正常运行。修改后的配置如下：

name: Build & Deploy to Netlify
on:
  push:
    branches:
      - master
  pull_request:
    types: [labeled, opened, synchronize, reopened]
jobs:
  build-deploy:
    if: "!contains(github.event.head_commit.message, 'ci skip')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js version from package.json
        uses: actions/setup-node@v3
        with:
          node-version-file: 'package.json'
      - name: Npm install
        run: npm ci
      - name: Deploy to Netlify
        uses: netlify/actions/cli@master
        with:
          args: deploy --prod --build
        env:
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_TEST_SITE_ID }}
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

说明：--build参数会触发netlify.toml中定义的构建命令和插件，无需手动指定--dir，Netlify会自动识别publish目录。

2. 保留netlify.toml的插件配置 #

不要移除@netlify/plugin-nextjs，它是Next.js在Netlify上正常运行的核心依赖，你的原配置是正确的：

[build]
command = "npm run build"
publish = ".next"

[[plugins]]
package = "@netlify/plugin-nextjs"

3. 确认Netlify站点的UI构建设置已完全禁用 #

进入Netlify站点的Settings > Build & deploy > Continuous deployment：

• 将Build command留空
• 将Publish directory留空
  确保Netlify不会用UI端的配置覆盖CLI和netlify.toml的设置。

4. 验证部署结果 #

重新触发GitHub Actions部署后，查看Netlify的部署日志，应该能看到@netlify/plugin-nextjs的运行日志，同时在站点的Functions页面会生成_next开头的函数。此时访问站点，页面应该能正常加载。

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