Next.js 静态导出部署 GitHub Pagesoutput: export、basePath 与 git subtree 完整实战【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本篇以 Next.js 官方仓库中的 github-pages 示例 为主体讲解如何将一个纯静态的 Next.js 应用导出为静态文件并发布到 GitHub Pages。读完后你将掌握output: export静态导出的配置方式、basePath前缀的正确写法及其在源码中的校验规则以及基于git subtree push的免 CI 部署脚本的完整原理与操作步骤。场景说明为什么 Next.js 可以部署到 GitHub PagesGitHub Pages 只能托管纯静态文件没有 Node.js 运行时。因此部署到 Pages 的前提是应用不依赖任何服务端渲染或 API 路由能够被 Next.js 完整地静态导出为一组 HTML/CSS/JS 文件。官方 github-pages 示例 正是为此设计的最小可运行模板其 README 开头即说明This example supports deploying a statically exported Next.js application to GitHub Pages.示例同时给出一条关键约束导出的out目录不应被版本控制系统忽略若.gitignore中写有out/需将其移除因为部署脚本会把out/内容提交到 Git 并推送。示例代码结构该示例采用 App Router 组织代码文件布局如下文件作用app/layout.tsx根布局注入 Inter 字体与metadatatitle/descriptionapp/page.tsx首页通过next/link链接到/aboutapp/about/page.tsx关于页包含返回首页的链接next.config.js核心配置文件启用静态导出与 basePathpackage.json定义dev/build/deploy三个脚本三个页面全部是纯静态内容组件直接返回 JSX没有任何async数据获取这是它能被成功静态导出的根本原因。根布局还使用了next/font/google加载 Inter 字体——字体文件会在构建时本地化处理同样不需要运行时。核心配置output: export 与 basePathnext.config.js 的全部内容只有两行它们是整篇部署方案的灵魂/** type {import(next).NextConfig} */ const nextConfig { output: export, basePath: /gh-pages-test, }; module.exports nextConfig;1. output: exportoutput: export告诉 Next.js 在next build时不做常规的.next服务端产物输出而是执行静态导出把所有页面预渲染为 HTML连同客户端 JS、字体等静态资源一起写入项目根目录的out/文件夹。部署脚本后续操作的正是这个out/目录。2. basePath: 与仓库名匹配的路径前缀GitHub Pages 的项目站点地址形如https://github-user-name.github.io/github-project-name/站点挂载在仓库名构成的路径前缀下而不是域名根路径。因此所有页面、路由、静态资源 URL 都必须带上这个前缀这就是basePath的职责。README 给出的配置规则是对于形如https://github.com/user/repo的仓库将basePath更新为/repo。示例中写的/gh-pages-test即是一个仓库名占位符使用时需替换为你自己的仓库名。basePath的写法在 Next.js 源码中有严格校验见 packages/next/src/server/config.ts必须为空字符串或以/开头否则抛出Specified basePath has to start with a /不能以/结尾否则抛出Specified basePath should not end with /当basePath有效且未显式配置assetPrefix时assetPrefix会默认继承为basePath即静态资源 URL 自动带上同一前缀——这正是示例无需额外配置资源前缀的原因。另外从 请求归一化层 的不变量basePath must be set and cannot be /可以看出basePath 一旦被设置它必须是一个有意义的路径前缀单独一个/是非法值。提示如果你把应用部署到 GitHub 用户/组织主页user.github.io根路径而非项目子路径则不需要basePath本方案针对的是项目站点这一最常见场景。部署脚本一条命令完成构建与推送package.json 中的deploy脚本是整套方案的自动化核心next build touch out/.nojekyll git add out/ git commit -m Deploy git subtree push --prefix out origin gh-pages逐段拆解next build执行静态导出生成out/目录touch out/.nojekyll创建空的.nojekyll文件。GitHub Pages 默认使用 Jekyll 处理仓库文件遇到下划线开头的目录Next.js 静态资源中常见_next风格的路径约定可能引发处理异常或行为差异.nojekyll的存在会显式关闭 Jekyll 处理保证文件原样发布git add out/ git commit -m Deploy把导出产物提交到本地仓库再次印证 README 中“out目录不应被.gitignore忽略”的要求git subtree push --prefix out origin gh-pages这是整个脚本的精髓。它无需 CI、无需额外依赖利用 Git 原生的subtree机制把out/子目录的全部历史与最新内容单独推送到远端的gh-pages分支。gh-pages分支的根目录就对应out/的内容与 GitHub Pages“以分支根目录为站点根”的要求即下文 Steps 中的/root选项完全吻合。完整部署步骤以下 7 步完整继承自 examples/github-pages/README.md新建一个public的 GitHub 仓库编辑next.config.js让basePath与你的 GitHub 仓库名匹配给定https://github.com/user/repo把basePath更新为/repo把脚手架代码推送到main分支运行deploy脚本如npm run deploy它会自动创建gh-pages分支在 GitHub 仓库Settings → Pages → Branch中选择gh-pages分支并指定/root文件夹点击Save对项目做一次任意改动再次运行deploy脚本把改动推送到 GitHub Pages。完成后站点地址形如https://github-user-name.github.io/github-project-name/获取示例工程仓库 README 提供了通过create-next-app脚手架一键生成该示例的命令三种包管理器任选其一在目标目录执行即可npx create-next-app --example github-pages github-pages-appyarn create next-app --example github-pages github-pages-apppnpm create next-app --example github-pages github-pages-app生成的工程依赖仅包含next、react、react-dom及 TypeScript 相关包见示例 package.jsondev脚本对应本地开发build脚本对应纯构建验证deploy脚本对应一键发布。使用边界与注意事项仅适用于纯静态应用output: export导出的产物没有服务端运行时API 路由、getServerSideProps、服务端组件数据获取等能力都不可用。仓库错误文档目录中专门收录了 api-routes-static-export 错误说明 和 export-no-custom-routes 错误说明描述的就是静态导出场景下这些能力受限时的报错可作为排查参考。basePath 必须与仓库名同步若后续重命名 GitHub 仓库务必同步更新next.config.js中的basePath并重新部署否则页面可访问但样式、脚本等资源会因前缀不匹配而加载失败。out 目录保持可提交确认.gitignore没有把out/排除否则git add out/阶段会静默失败。部署链路无 CI本方案完全依赖本地git subtree push适合个人博客、文档站等低频更新场景对频繁迭代的项目可参考仓库中另一个 with-static-export 示例 了解静态导出的更多配置变体或自行将deploy步骤迁移到 CI 中执行。总结来说该方案的技术内核只有三件事output: export产出纯静态out/目录、basePath对齐 Pages 的子路径挂载前缀、git subtree push把产物推上gh-pages分支。三者缺一站点都会出现页面 404、资源 404 或分支不存在的典型故障按上述步骤完整执行后即可得到一个可直接访问的 GitHub Pages 站点。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Next.js 静态导出部署 GitHub Pages：output: export、basePath 与 git subtree 完整实战
Next.js 静态导出部署 GitHub Pagesoutput: export、basePath 与 git subtree 完整实战【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本篇以 Next.js 官方仓库中的 github-pages 示例 为主体讲解如何将一个纯静态的 Next.js 应用导出为静态文件并发布到 GitHub Pages。读完后你将掌握output: export静态导出的配置方式、basePath前缀的正确写法及其在源码中的校验规则以及基于git subtree push的免 CI 部署脚本的完整原理与操作步骤。场景说明为什么 Next.js 可以部署到 GitHub PagesGitHub Pages 只能托管纯静态文件没有 Node.js 运行时。因此部署到 Pages 的前提是应用不依赖任何服务端渲染或 API 路由能够被 Next.js 完整地静态导出为一组 HTML/CSS/JS 文件。官方 github-pages 示例 正是为此设计的最小可运行模板其 README 开头即说明This example supports deploying a statically exported Next.js application to GitHub Pages.示例同时给出一条关键约束导出的out目录不应被版本控制系统忽略若.gitignore中写有out/需将其移除因为部署脚本会把out/内容提交到 Git 并推送。示例代码结构该示例采用 App Router 组织代码文件布局如下文件作用app/layout.tsx根布局注入 Inter 字体与metadatatitle/descriptionapp/page.tsx首页通过next/link链接到/aboutapp/about/page.tsx关于页包含返回首页的链接next.config.js核心配置文件启用静态导出与 basePathpackage.json定义dev/build/deploy三个脚本三个页面全部是纯静态内容组件直接返回 JSX没有任何async数据获取这是它能被成功静态导出的根本原因。根布局还使用了next/font/google加载 Inter 字体——字体文件会在构建时本地化处理同样不需要运行时。核心配置output: export 与 basePathnext.config.js 的全部内容只有两行它们是整篇部署方案的灵魂/** type {import(next).NextConfig} */ const nextConfig { output: export, basePath: /gh-pages-test, }; module.exports nextConfig;1. output: exportoutput: export告诉 Next.js 在next build时不做常规的.next服务端产物输出而是执行静态导出把所有页面预渲染为 HTML连同客户端 JS、字体等静态资源一起写入项目根目录的out/文件夹。部署脚本后续操作的正是这个out/目录。2. basePath: 与仓库名匹配的路径前缀GitHub Pages 的项目站点地址形如https://github-user-name.github.io/github-project-name/站点挂载在仓库名构成的路径前缀下而不是域名根路径。因此所有页面、路由、静态资源 URL 都必须带上这个前缀这就是basePath的职责。README 给出的配置规则是对于形如https://github.com/user/repo的仓库将basePath更新为/repo。示例中写的/gh-pages-test即是一个仓库名占位符使用时需替换为你自己的仓库名。basePath的写法在 Next.js 源码中有严格校验见 packages/next/src/server/config.ts必须为空字符串或以/开头否则抛出Specified basePath has to start with a /不能以/结尾否则抛出Specified basePath should not end with /当basePath有效且未显式配置assetPrefix时assetPrefix会默认继承为basePath即静态资源 URL 自动带上同一前缀——这正是示例无需额外配置资源前缀的原因。另外从 请求归一化层 的不变量basePath must be set and cannot be /可以看出basePath 一旦被设置它必须是一个有意义的路径前缀单独一个/是非法值。提示如果你把应用部署到 GitHub 用户/组织主页user.github.io根路径而非项目子路径则不需要basePath本方案针对的是项目站点这一最常见场景。部署脚本一条命令完成构建与推送package.json 中的deploy脚本是整套方案的自动化核心next build touch out/.nojekyll git add out/ git commit -m Deploy git subtree push --prefix out origin gh-pages逐段拆解next build执行静态导出生成out/目录touch out/.nojekyll创建空的.nojekyll文件。GitHub Pages 默认使用 Jekyll 处理仓库文件遇到下划线开头的目录Next.js 静态资源中常见_next风格的路径约定可能引发处理异常或行为差异.nojekyll的存在会显式关闭 Jekyll 处理保证文件原样发布git add out/ git commit -m Deploy把导出产物提交到本地仓库再次印证 README 中“out目录不应被.gitignore忽略”的要求git subtree push --prefix out origin gh-pages这是整个脚本的精髓。它无需 CI、无需额外依赖利用 Git 原生的subtree机制把out/子目录的全部历史与最新内容单独推送到远端的gh-pages分支。gh-pages分支的根目录就对应out/的内容与 GitHub Pages“以分支根目录为站点根”的要求即下文 Steps 中的/root选项完全吻合。完整部署步骤以下 7 步完整继承自 examples/github-pages/README.md新建一个public的 GitHub 仓库编辑next.config.js让basePath与你的 GitHub 仓库名匹配给定https://github.com/user/repo把basePath更新为/repo把脚手架代码推送到main分支运行deploy脚本如npm run deploy它会自动创建gh-pages分支在 GitHub 仓库Settings → Pages → Branch中选择gh-pages分支并指定/root文件夹点击Save对项目做一次任意改动再次运行deploy脚本把改动推送到 GitHub Pages。完成后站点地址形如https://github-user-name.github.io/github-project-name/获取示例工程仓库 README 提供了通过create-next-app脚手架一键生成该示例的命令三种包管理器任选其一在目标目录执行即可npx create-next-app --example github-pages github-pages-appyarn create next-app --example github-pages github-pages-apppnpm create next-app --example github-pages github-pages-app生成的工程依赖仅包含next、react、react-dom及 TypeScript 相关包见示例 package.jsondev脚本对应本地开发build脚本对应纯构建验证deploy脚本对应一键发布。使用边界与注意事项仅适用于纯静态应用output: export导出的产物没有服务端运行时API 路由、getServerSideProps、服务端组件数据获取等能力都不可用。仓库错误文档目录中专门收录了 api-routes-static-export 错误说明 和 export-no-custom-routes 错误说明描述的就是静态导出场景下这些能力受限时的报错可作为排查参考。basePath 必须与仓库名同步若后续重命名 GitHub 仓库务必同步更新next.config.js中的basePath并重新部署否则页面可访问但样式、脚本等资源会因前缀不匹配而加载失败。out 目录保持可提交确认.gitignore没有把out/排除否则git add out/阶段会静默失败。部署链路无 CI本方案完全依赖本地git subtree push适合个人博客、文档站等低频更新场景对频繁迭代的项目可参考仓库中另一个 with-static-export 示例 了解静态导出的更多配置变体或自行将deploy步骤迁移到 CI 中执行。总结来说该方案的技术内核只有三件事output: export产出纯静态out/目录、basePath对齐 Pages 的子路径挂载前缀、git subtree push把产物推上gh-pages分支。三者缺一站点都会出现页面 404、资源 404 或分支不存在的典型故障按上述步骤完整执行后即可得到一个可直接访问的 GitHub Pages 站点。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考