Next.js部署GitHub Pages报错：找不到build目录怎么解决？

核心原因 #

Next.js的构建产物目录和Create React App（CRA）不同：CRA默认输出到build，但Next.js静态导出的产物目录是out（默认构建是.next，但GitHub Pages仅支持静态文件，必须用静态导出模式），所以你执行gh-pages -d build会找不到对应目录。

具体解决步骤 #

1. 配置静态导出的构建命令
   在项目根目录的package.json中，修改build和deploy命令：

   "scripts": {
     "dev": "next dev",
     "build": "next build && next export",
     "start": "next start",
     "deploy": "gh-pages -d out --dotfiles"
   }
   

   • next build && next export会生成静态可部署的out目录
   • --dotfiles参数确保gh-pages上传隐藏文件（比如Next.js生成的.nojekyll，避免GitHub Pages的Jekyll处理干扰）

2. 适配GitHub Pages的路径（必做）
   创建或修改next.config.js，添加路径适配配置（Next.js 13+推荐）：

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     output: 'export', // Next.js 13+ 静态导出标识
     basePath: '/你的仓库名称', // 例如仓库名为breeze-next，就写'/breeze-next'
     trailingSlash: true, // 避免路由404问题
   }
   
   module.exports = nextConfig
   

3. 重新执行部署流程

   • 清理旧构建产物：

     # macOS/Linux
     rm -rf out .next
     # Windows
     rmdir /s /q out .next
     

   • 重新构建：npm run build，确认项目根目录生成了out文件夹
   • 部署到GitHub Pages：npm run deploy

4. 检查GitHub Pages设置
   登录GitHub仓库，进入「Settings」→「Pages」，确认源选择gh-pages分支的/root目录，保存设置后等待部署完成。

额外排查点 #

• 如果之前部署过导致gh-pages分支异常，可执行gh-pages -d out --clean强制清理旧分支后重新部署
• 确保gh-pages包已正确安装：npm list gh-pages，若未安装重新执行npm install --save-dev gh-pages

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