如何用.gitlab-ci.yml为NextJS搭建Gitlab CI/CD流水线并解决Netlify部署404问题

问题根因 #

你部署时指定的目录.next是NextJS的构建缓存目录，并非可直接对外提供访问的静态产物目录，Netlify无法识别该目录下的路由规则，因此访问时返回404。

解决方案 #

方案1：使用静态导出模式（适用于无SSR/服务端API路由需求的项目） #

• 修改项目package.json的build命令：

  "scripts": {
    "build": "next build && next export"
  }
  

  执行该命令后会生成out目录，该目录为完整的静态站点产物。
• 调整CI的yml配置：

  stages:
    - lint
    - build
    - deploy
  lint project:
    stage: lint
    image: node:20 # 建议替换为LTS版本的Node，兼容性更好
    script:
      - npm install
      - npm run lint
  build project:
    stage: build
    image: node:20
    script:
      - npm install
      - npm run build
    artifacts:
      paths: 
        - out # 替换为静态导出的产物目录
  netlify:
    stage: deploy
    image: node:20
    script:
      - npm install -g netlify-cli
      - netlify deploy --dir=out --prod # 部署目录修改为out
  

  你可以提前在CI环境变量中配置NETLIFY_AUTH_TOKEN和NETLIFY_SITE_ID，不需要额外配置路径即可完成认证。

方案2：保留NextJS服务端能力（适用于使用SSR/API路由的项目） #

• 在项目根目录新增netlify.toml配置文件，内容如下：

  [build]
    command = "npm run build"
    publish = ".next"
  
  [[plugins]]
    package = "@netlify/plugin-nextjs"
  

• 安装Netlify官方NextJS插件：

  npm install @netlify/plugin-nextjs --save-dev
  

• 调整CI部署阶段的命令，不需要手动指定部署目录，插件会自动处理产物适配：

  netlify:
    stage: deploy
    image: node:20
    script:
      - npm install -g netlify-cli
      - netlify deploy --prod
  

模板复用优化建议 #

• 固定Node版本为LTS版本（如18、20），避免非LTS版本的兼容性问题
• 为CI添加依赖缓存配置，减少重复安装依赖的耗时
• 所有敏感信息（如Netlify认证令牌）都存在CI环境变量中，不要硬编码在配置文件内，适配不同项目的部署需求

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