Next.js 静态导出与 GitHub Pages 自动部署自定义域名、HTTPS 和百度验证实战前言对于个人作品展示、项目文档、技术博客等以内容展示为主的网站如果暂时不需要数据库、用户登录、文件上传和服务端接口可以将 Next.js 项目导出为静态文件并部署到 GitHub Pages。这种部署方式不需要单独维护服务器同时还能实现GitHub Actions 自动构建与发布自定义域名访问自动配置 HTTPS多页面静态路由JavaScript 动画和前端交互百度搜索资源平台验证robots.txt和sitemap.xml配置。本文以一个实际的 Next.js 静态网站为例记录从项目配置到公开上线的完整过程并重点分析部署中容易遇到的 DNS、404 和搜索验证问题。一、整体部署架构本次使用的部署流程如下本地 Next.js 项目 ↓ 提交到 GitHub 仓库 ↓ 触发 GitHub Actions ↓ 安装依赖并执行构建 ↓ 生成 out 静态目录 ↓ 上传 GitHub Pages 部署产物 ↓ 通过自定义域名访问这种方案适合个人作品集企业展示页产品介绍页项目文档静态博客活动专题页面。不适合直接运行以下功能Node.js 服务端接口数据库实时读写用户登录和注册后台内容管理服务端文件上传依赖运行时服务器的动态渲染无法在构建阶段确定参数的动态页面。因此在改造之前应先确认项目是否可以静态化。二、配置 Next.js 静态导出在 Next.js 配置文件中启用静态导出。如果项目使用next.config.js可以参考/** type {import(next).NextConfig} */constnextConfig{output:export,trailingSlash:true,images:{unoptimized:true,},};module.exportsnextConfig;如果项目使用next.config.mjsconstnextConfig{output:export,trailingSlash:true,images:{unoptimized:true,},};exportdefaultnextConfig;1.output: export该配置会让 Next.js 在构建完成后生成静态 HTML、CSS 和 JavaScript 文件。构建产物默认位于out/2.trailingSlash: true启用后页面会输出为目录形式。例如/about/对应的文件为out/about/index.html这种路径形式在 GitHub Pages 等静态托管平台中通常更加稳定。3.images.unoptimized: trueNext.js 默认图片优化功能需要服务端参与。GitHub Pages 只能托管静态资源因此需要关闭服务端图片优化或者改用普通img标签及提前压缩好的图片。三、处理动态路由如果项目存在动态路由例如app/projects/[slug]/page.tsx静态导出时需要提前告诉 Next.js 应当生成哪些页面。可以通过generateStaticParams提供参数constprojects[{slug:project-a,title:项目 A,},{slug:project-b,title:项目 B,},];exportfunctiongenerateStaticParams(){returnprojects.map((project)({slug:project.slug,}));}最终会生成out/projects/project-a/index.html out/projects/project-b/index.html如果动态参数只能在用户访问时从服务器获取就不适合直接导出到 GitHub Pages。四、本地执行构建测试完成配置后先不要立即推送。在本地执行npminstallnpmrun build如果使用锁文件并希望严格按照锁定版本安装可以使用npmcinpmrun build构建成功后应出现out/典型目录结构out/ ├── index.html ├── 404.html ├── about/ │ └── index.html ├── projects/ │ ├── project-a/ │ │ └── index.html │ └── project-b/ │ └── index.html ├── _next/ ├── images/ ├── robots.txt └── sitemap.xml部署前建议重点检查out/index.html是否存在所有项目详情页是否生成图片路径是否正确CSS 和 JavaScript 是否正常刷新二级页面是否出现 404页面是否仍然依赖服务端接口页面是否包含错误的绝对路径public中的文件是否复制到out根目录。五、创建 GitHub Pages 自动部署工作流在项目中创建文件.github/workflows/deploy.yml写入name:Deploy Next.js site to GitHub Pageson:push:branches:-mainworkflow_dispatch:permissions:contents:readpages:writeid-token:writeconcurrency:group:github-pagescancel-in-progress:falsejobs:build:runs-on:ubuntu-lateststeps:-name:Checkout repositoryuses:actions/checkoutv4-name:Setup Node.jsuses:actions/setup-nodev4with:node-version:20cache:npm-name:Install dependenciesrun:npm ci-name:Configure GitHub Pagesuses:actions/configure-pagesv5-name:Build Next.js projectrun:npm run build-name:Upload static siteuses:actions/upload-pages-artifactv4with:path:./outdeploy:needs:buildruns-on:ubuntu-latestenvironment:name:github-pagesurl:${{steps.deployment.outputs.page_url}}steps:-name:Deploy to GitHub Pagesid:deploymentuses:actions/deploy-pagesv4工作流的核心过程是拉取代码 → 安装 Node.js → 安装依赖 → 执行 npm run build → 上传 out 目录 → 发布到 GitHub Pages需要特别注意path:./out这里必须指向真正的静态构建产物。如果错误上传.next、项目根目录或其他文件夹线上网站可能出现空白页、404 或资源加载失败。六、在 GitHub 中启用 Pages进入仓库设置 → GitHub Pages在“构建和部署”的来源中选择GitHub Actions然后将代码推送到main分支gitadd.gitcommit-mconfigure GitHub Pages deploymentgitpush origin main进入仓库中的操作查看工作流状态。绿色表示部署成功红色表示失败。如果失败可以点开具体步骤查看日志。常见错误包括npm ci找不到锁文件Node.js 版本不兼容TypeScript 编译失败ESLint 检查失败动态路由没有生成静态参数图片优化功能与静态导出冲突构建完成但没有生成out目录。七、配置自定义域名GitHub Pages 默认地址通常类似https://username.github.io如果已经购买独立域名可以在仓库 → 设置 → GitHub Pages → 自定义域填写www.example.com然后到域名服务商的 DNS 控制台添加 CNAME 记录记录类型CNAME 主机记录www 记录值username.github.io注意记录值不要填写https://不要在结尾添加/同一个www记录不能同时存在冲突的 A 记录DNS 生效需要一定时间GitHub 会自动检查域名配置。正确关系如下www.example.com ↓ username.github.io八、配置不带www的根域名如果还希望下面这个地址能够访问example.com需要为根域名添加解析。根域名的主机记录通常填写然后添加 GitHub Pages 的 A 记录地址。结构如下记录类型A 主机记录 记录值GitHub Pages 官方提供的 IP最终建议统一到一个正式域名例如https://www.example.com这样可以避免https://example.com https://www.example.com被搜索引擎识别为两个不同的网站版本。网站中的以下内容也应保持一致canonicalsitemapOpen GraphJSON-LD站内链接robots.txt。九、开启强制 HTTPSDNS 检查成功后GitHub Pages 会为自定义域名签发 HTTPS 证书。证书生成后可以在 Pages 设置中勾选强制 HTTPS启用后http://www.example.com会自动跳转到https://www.example.com如果“强制 HTTPS”暂时无法勾选通常是以下原因DNS 尚未完全生效CNAME 配置错误根域名存在冲突记录GitHub 仍在签发证书自定义域名刚刚变更。此时不要频繁删除和重新添加域名否则可能延长证书签发时间。十、配置百度搜索资源平台文件验证网站部署完成后可以添加到百度搜索资源平台。文件验证通常会提供一个 HTML 文件例如baidu_verify_codeva-xxxxxxxx.html对于 Next.js 静态导出项目应将文件放入public/目录结构示例project/ ├── public/ │ ├── images/ │ ├── robots.txt │ └── baidu_verify_codeva-xxxxxxxx.html ├── app/ ├── package.json └── next.config.js执行构建后文件应出现在out/baidu_verify_codeva-xxxxxxxx.html部署成功后可以通过以下地址访问https://www.example.com/baidu_verify_codeva-xxxxxxxx.html只有该地址能够直接打开百度才能完成验证。验证成功后不要删除这个文件。十一、百度验证文件出现 404 的原因在实际部署中经常会出现本地 public 中存在验证文件 但是线上访问返回 404这通常不是百度的问题而是文件没有进入最终部署产物。1. 检查构建产物执行npmrun build然后检查out/baidu_verify_codeva-xxxxxxxx.html是否存在。如果public中有文件但out中没有说明构建配置存在问题。2. 检查文件名文件名必须完全一致包括字母大小写连字符下划线扩展名。GitHub Pages 使用 Linux 文件系统文件名大小写敏感。例如Verify.html verify.html会被视为两个不同文件。3. 检查最新提交是否推送执行gitstatusgitlog-1gitremote-v确认验证文件已经提交gitaddpublic/baidu_verify_codeva-xxxxxxxx.htmlgitcommit-madd Baidu verification filegitpush origin main4. 检查 GitHub Actions 状态进入仓库 → 操作确认最新工作流已经成功。本地文件存在并不代表远程仓库和线上网站已经更新。5. 检查上传目录工作流必须上传path:./out如果上传目录错误即使构建成功验证文件也不会出现在网站根目录。6. 等待部署节点更新GitHub Actions 显示成功后线上节点仍可能存在短暂延迟。可以等待几分钟再使用无痕窗口访问https://www.example.com/baidu_verify_codeva-xxxxxxxx.html也可以临时增加查询参数排除浏览器缓存https://www.example.com/baidu_verify_codeva-xxxxxxxx.html?v2十二、配置 robots.txt在public目录创建robots.txt内容示例User-agent: * Allow: / Sitemap: https://www.example.com/sitemap.xml构建后应能够访问https://www.example.com/robots.txt需要避免出现Disallow: /该配置会阻止搜索引擎抓取整个网站。还需要检查正式页面中是否存在metanamerobotscontentnoindex/如果线上页面包含noindex搜索引擎可能不会将页面加入索引。十三、创建 sitemap.xml网站地图用于列出网站中的重要页面。示例?xml version1.0 encodingUTF-8?urlsetxmlnshttp://www.sitemaps.org/schemas/sitemap/0.9urllochttps://www.example.com//loc/urlurllochttps://www.example.com/about//loc/urlurllochttps://www.example.com/projects/project-a//loc/urlurllochttps://www.example.com/projects/project-b//loc/url/urlset将文件放入public/sitemap.xml线上地址https://www.example.com/sitemap.xml然后可以在百度搜索资源平台的普通收录功能中提交该地址。网站地图的作用是帮助搜索引擎发现页面不代表提交后一定立即收录。十四、添加部署前检查脚本为了避免后续修改时误删验证文件、Sitemap 或 robots 文件可以在构建完成后增加自动检查。创建scripts/check-static-files.mjs内容importfsfromnode:fs;importpathfromnode:path;constoutputDirectorypath.join(process.cwd(),out);constrequiredFiles[index.html,robots.txt,sitemap.xml,baidu_verify_codeva-xxxxxxxx.html,];constmissingFiles[];for(constfileofrequiredFiles){constfilePathpath.join(outputDirectory,file);if(!fs.existsSync(filePath)){missingFiles.push(file);}}if(missingFiles.length0){console.error(静态构建检查失败缺少以下文件);for(constfileofmissingFiles){console.error(-${file});}process.exit(1);}console.log(静态构建检查通过);然后在package.json中增加{scripts:{build:next build,check:static:node scripts/check-static-files.mjs}}GitHub Actions 中增加-name:Build Next.js projectrun:npm run build-name:Validate static filesrun:npm run check:static这样如果后续构建缺少必要文件工作流会停止部署避免错误版本上线。十五、常见问题总结1. 静态网站还能使用动画吗可以。静态部署仍然能够运行浏览器端 JavaScript因此滚动动画、轮播、弹窗、菜单、卡片交互等功能都可以保留。2. 为什么二级页面刷新后出现 404应检查是否启用了trailingSlash页面是否真正生成到out动态路由是否配置了静态参数内部链接是否指向正确路径。3. 为什么图片部署后不显示常见原因包括使用了错误的绝对路径文件名大小写不一致图片没有放在publicnext/image仍然依赖服务端优化构建后路径发生变化。4. 为什么 DNS 检查一直失败应检查CNAME 是否指向正确地址记录值是否误加https://是否存在同名 A 或 AAAA 记录DNS 是否尚未完全生效自定义域名是否填写正确。5. 为什么验证文件本地存在但线上 404重点检查public 文件 → out 构建产物 → Git 提交 → 远程 main 分支 → GitHub Actions → Pages 部署结果任何一个环节没有完成线上都可能访问不到。十六、总结将 Next.js 网站部署到 GitHub Pages涉及的不只是执行一次构建。完整流程包括静态导出配置动态路由处理本地构建检查GitHub Actions 自动部署自定义域名 DNS 配置HTTPS 证书签发百度文件验证robots.txt 和 sitemap.xml404 与构建产物排查部署前自动检查。对于内容展示型网站这套方案可以在不维护独立服务器的情况下获得稳定的自动部署和独立域名访问能力。真正需要重点关注的是构建产物。无论本地源代码看起来是否正确最终线上网站实际发布的都是out/因此排查问题时应始终围绕源文件是否存在 → 构建产物是否存在 → 远程提交是否存在 → 工作流是否成功 → 线上文件是否可访问建立清晰的检查链路后大部分 GitHub Pages 部署问题都可以快速定位。
