问题检查 & 解决方式
Next.js 静态导出 SSG 部署到GitHub Page后，访问出现JavaScript，CSS无法正常加载。
在开发者工具network面板中，对应的文件404；
在浏览器中打开对应报错文件的地址，会出现Next.js默认的404页面；
.nojekyll 文件
首先检查：
GitHub Pages部署的仓库根目录是否缺失.nojekyll文件。
如果缺失，大部分是该问题导致，缺失该文件会导致_next以下划线_开头的目录被忽略，导致出错。
.nojekyll 是一个空文件，放在静态站点的根目录中，用来告诉 GitHub Pages：
不要使用默认的 Jekyll 处理机制，尤其是不要忽略以下划线
_开头的目录（例如Next.js的_next/静态资源目录）。
❌ https://username.github.io/repo-name/_next/static/xxx.js → 404
✅ 添加 .nojekyll 后可正常访问basePath 和 assetPrefix 配置
其次检查：
检查：index.html中引用的JavaScript、CSS路径，是否包含仓库名称子目录；
GitHub Pages支持三种类型：项目页、用户页、组织页。 项目页通常托管在https://username.github.io/repo-name/，因此资源路径需要包含仓库名称作为子目录。 例如：username.github.io/your-repository-name，需要构建工具以及框架进行配置调整，否则，会导致资源路径不对，缺少子路径引起404。
对于 GitHub Pages 这类子路径部署，Next.js 的静态资源（如 JS、CSS）路径也必须修改，推荐如下：
Loading...🔧 解释：
basePath: 修改页面路由前缀（如/about→/tailwindcss-typography-demo/about）。assetPrefix: 修改静态资源路径前缀，确保_next/的加载路径正确。
✅ basePath / assetPrefix 配置效果对比表
| 场景 | 没有设置 basePath / assetPrefix | 正确设置后 |
|---|---|---|
| 页面访问路径 | /about（默认） | /your-repo-name/about（带仓库名前缀） |
| 静态资源路径（JS/CSS） | _next/static/...，将 404 | /your-repo-name/_next/static/...，可正常加载 |
| 首页路径 | https://username.github.io/ 会显示 404 或空白 | https://username.github.io/your-repo-name/ 正常显示首页 |
| 点击跳转链接 | <a href="/page"> 指向错误路径 | <Link href="/page"> 会自动加上 basePath |
| 推荐配置 | 🚫 会出现路径缺失、资源无法加载的问题 | ✅ 推荐用于 GitHub Pages 的子路径部署 |
重新编译部署后。
最后：
检查所有的超链接，如果使用的是<a>，替换成Next.js的Link组件，否则可能无法正确处理路径前缀，导致 404。
import Link from "next/link"原生 HTML 的 <a> 标签不会自动处理 basePath，容易引发路径错误，建议统一使用 Next.js 提供的 Link 组件。
经过上述的检查，应该可以解决大部分出现的问题，如果仍存在错误，需要检查静态资源文件是否上传到仓库中。
推荐部署流程（gh-pages 自动化）
若之前是手动将out目录部署到GitHub Pages，建议采用自动化工具进行部署。
能自动将构建好的out目录发布到gh-pages分支。
该方式自动化程度高，也是社区里最常用的部署方式。
它会帮你把 out 目录的内容发布到一个专门用于 GitHub Pages 的 gh-pages 分支上，而不影响你的主分支。
- 安装
gh-pages
Loading...- 修改
package.json，在scripts部分增加一个新的部署deploy脚本。
"scripts": {
"dev": "next dev --turbopack",
"build": "next build",
"start": "next start",
"lint": "next lint",
"deploy": "next build && gh-pages -d out --nojekyll"
},next build：首先执行构建，确保out目录是最新的；gh-pages -d out --nojekyll：将out目录中的内容部署到gh-pages分支，同时确保生成.nojekyll空文件，避免影响_next等静态资源目录；
- 运行部署命令
pnpm run deploy该命令会自动创建一个 gh-pages 分支（如果不存在的话），将 out 目录中的文件推送到这个分支，然后发布到 GitHub Pages。
使用该自动化工具后，无需手动进入 GitHub 仓库的 Settings → Pages 页面配置，即可完成部署。
其他：为什么选择 GitHub Pages？
有些朋友可能会疑惑：“Next.js 本就是 Vercel 出品，难道不该部署在 Vercel 吗？”
确实，Vercel 是部署 Next.js 的首选平台，两者深度集成，支持 SSR、ISR、动态 API 路由等高级特性，部署体验极佳。但这也意味着它依赖 Vercel 提供的运行时资源，如 Node.js 环境。
然而在以下场景中，GitHub Pages 仍然是一个值得考虑的选择：
- 🔹 仅使用
Next.js的静态导出（output: "export"）功能，不依赖SSR等运行时特性； - 🔹 构建的是教程
Demo、项目文档、个人博客等纯前端内容； - 🔹 希望使用
GitHub提供的免费静态托管资源，而不是占用Vercel的Hobby配额； - 🔹 项目已托管在
GitHub，部署到Pages流程更简单、可控； - 🔹 对流量、性能要求不高，更重视部署可维护性和公开透明性。
总之，GitHub Pages 是部署静态站点的轻量替代方案，尤其适合资源有限或纯前端展示类项目。
常见问题 FAQ
❓ .nojekyll 文件怎么生成？
.nojekyll 是一个空文件，用于防止 GitHub Pages 忽略 _next/ 目录。可以手动创建，也可以通过部署命令自动生成：
方式一：命令行创建
touch out/.nojekyll方式二：使用 gh-pages 工具自动添加
gh-pages -d out --nojekyll