如果你手里已经有一个Hugo站点或者正打算从Hexo、Jekyll迁过来那“把Hugo部署到GitHub Pages”这件事十有八九是你绕不开的一步。我第一次折腾这个组合的时候本以为就是“push代码到仓库”这么简单结果被一堆细节卡了两天本地预览一切正常推到线上就是纯白页面样式全丢了README倒是显示出来了网页死活不出来。后来我把GitHub Pages的部署原理、Hugo的构建逻辑、Actions工作流的执行顺序全部捋了一遍才彻底搞明白问题出在哪。这篇文章不打算写那种“照着敲一遍就能跑”的教程而是把我自己从零到一部署Hugo到GitHub Pages的全过程、每一步背后的原理、以及踩过的坑都摊开来讲。无论你是刚接触静态站生成器的新手还是已经写过几篇博客想折腾自动化部署的老手这篇都能给你一些可实操的东西。1. 部署方案与整体思路拆解1.1 为什么是“Hugo GitHub Pages”先说说这个组合为什么会成为很多人的首选。Hugo是Go语言写的静态站点生成器速度极快几千篇文章的站点构建也就几秒种的事而且不依赖Node.js环境装上就能用。GitHub Pages则是GitHub提供的静态网页托管服务免费、支持自定义域名、自带HTTPS对个人博客和小型项目文档来说完全够用。这两者搭配的逻辑其实很直白Hugo负责把Markdown源文件变成一堆HTML、CSS、JS静态文件GitHub Pages负责把这堆静态文件挂在公网上。整个过程不需要服务器、不需要数据库、不需要后端语言发布的就是纯静态内容访问速度快维护成本几乎为零。我之前用Hexo的时候每次部署都要在本地装Node环境、装一堆npm包换一台电脑就得重新配一轮。换成Hugo之后单个可执行文件拷过去就能用加上GitHub Actions做云端构建本地连Hugo环境都不用装了直接把源代码推到仓库里剩下的全自动。这种“零运维”的感觉是这套方案最吸引我的地方。1.2 两个容易混淆的概念站点仓库与Pages仓库很多新手第一次部署时会懵是因为没搞清楚GitHub Pages的两种托管形态。第一种是用户或组织主页仓库名必须叫“用户名.github.io”这个仓库发布出来的地址就是“https://用户名.github.io”。第二种是项目主页仓库名随意发布地址是“https://用户名.github.io/仓库名/”。这个区别直接影响Hugo配置里的baseURL参数。如果你是项目主页baseURL必须写成“https://用户名.github.io/仓库名/”结尾的斜杠不能漏漏了或者写错了线上页面的CSS和JS路径就全乱了表现出来就是“页面能打开但纯白没样式”。我第一次就是在这里栽的跟头后面细说。所以动手之前先想清楚你的仓库是哪种形态然后把这个URL牢牢记住后面配置、部署、排查问题全都要用到它。1.3 部署策略选择本地推送还是云端自动构建部署Hugo到GitHub Pages主流做法有三种我把它们的优缺点摆出来部署方式核心操作优点缺点本地构建后推送public目录本地运行hugo生成静态文件推到gh-pages分支简单直观随时可控每次都要本地装Hugo换电脑不方便推源码到main分支用Actions构建推送Markdown源文件Actions自动执行hugo构建并发布云端构建本地零依赖自动化程度高首次配置Actions需要一点学习成本直接推静态文件到main分支完全本地构建只推送public内容最原始GitHub端无需任何配置无法保留源文件提交记录混乱我个人强烈推荐第二种也就是用GitHub Actions做自动化构建。原因有三点第一本地只需要装Git连Hugo都不用装写文章、改配置、push剩下的交给云端第二GitHub官方提供了Hugo的构建缓存构建速度很快第三整个流程可复现哪怕换电脑、清空本地目录只要仓库还在随时能恢复到可发布状态。2. 环境准备与站点配置的核心细节2.1 本地Hugo环境的安装与版本选择虽然最终构建可以在云端完成但本地装一个Hugo依然是强烈建议的因为你要本地预览、写文章、调试布局。Hugo的安装在不同平台上有不同方式macOS用户可以用包管理器直接装Windows用户下载二进制包解压就能用Linux用户可以用Snap或直接下deb包。安装之后记得做两步验证第一步在终端里输入hugo version确认能输出版本号第二步确认版本是Extended版。这里有个细节很多人会忽略Hugo有两个发行版本普通版和Extended版如果你用了Sass/SCSS相关的主题普通版会直接构建报错提示你缺少相关功能。我建议所有人在Windows上无脑选hugo_extended那个包Linux下带extended字样的deb包macOS下用hugo公式它默认就是Extended。提示Hugo版本差异也会引发构建问题。比如某个主题在0.120版本下正常但你在本地用的是0.90版构建时可能报错。如果你需要跟GitHub Actions里的版本保持一致可以在hugo.toml里不锁定版本让Actions用最新版但本地建议安装和Actions相同的版本避免“本地正常、云端失败”的尴尬。2.2 站点初始化从零创建一个Hugo项目假设你还没有站点初始化流程很简单。在终端里进入你想要存放项目的目录执行hugo new site my-blog cd my-blog这会在当前目录下生成一个名为my-blog的文件夹里面有content、layouts、static、themes这些标准目录以及一个hugo.toml配置文件。不同版本的Hugo里这个配置文件可能是config.toml也可能是hugo.toml新版本里多为hugo.toml两者本质上是一样的。然后你需要一个主题。Hugo的主题机制和Hexo类似在themes目录下放一个主题文件夹然后在配置文件里指定启用哪个主题。多数主题的GitHub仓库都有git clone方式安装的说明比如git clone https://github.com/某个主题地址.git themes/你的主题名装完主题之后把主题自带的exampleSite里的配置示例复制一份到根目录或者对照着看搞清楚这个主题需要哪些配置项。每个主题的配置项差异很大但核心的那几个都跑不掉baseURL、languageCode、title、theme。这些配置直接影响站点能否正确生成和部署。2.3 配置文件关键项baseURL怎么填配置文件里最重要的就是baseURL它决定了Hugo生成的每个页面上所有静态资源引用的绝对路径的前缀是什么。如果你是用户主页形态仓库名是用户名.github.iobaseURL填baseURL https://用户名.github.io/如果你是项目主页形态仓库名是任意名字baseURL填baseURL https://用户名.github.io/仓库名/注意结尾必须有斜杠否则Hugo生成资源引用时会把最后一个路径段跟文件名拼在一起出现“/仓库名css/style.css”这种错误路径样式和脚本全部加载失败。怎么验证这个配置对不对呢本地启动预览后打开浏览器右键查看网页源代码看CSS和JS的引用路径前缀是否和baseURL完全一致。如果一致那线上至少不会出现纯白页如果不一致先改配置再继续。2.4 站点内容准备写一篇文章、生成一张页面配置完成后随便写一篇文章来验证流程。文章放在content/posts目录下文件名一般用日期和下划线组合比如2024-01-01-first-post.md这主要是为了归档排序方便。文件头部的front matter里至少要有title和date否则主题可能无法正常展示。--- title: 我的第一篇文章 date: 2024-01-01T10:00:0008:00 --- 这里是正文内容。然后本地执行hugo server -D-D参数的意思是“渲染草稿”也就是包含draft: true标记的页面。浏览器打开http://localhost:1313如果能看到文章页面说明站点本身没问题。按CtrlC停掉服务进入下一步。本地正常了才轮到部署。如果你本地这一步就没跑通那别急着push先在本地把问题解决不然到线上排查更麻烦。3. 仓库创建与Actions工作流实操3.1 创建GitHub仓库命名决定地址登录GitHub后点击新建仓库。这里分两种情况如果是用户主页形态仓库名必须严格填用户名.github.io。注意这个仓库是公开仓库还无所谓如果你用的是免费账号GitHub Pages要求公开仓库除非你付费开Private Pages。如果是项目主页形态仓库名随便填但你要额外注意项目主页的发布地址是“用户名.github.io/仓库名”这会影响后面baseURL的写法。我建议项目仓库名直接跟站点目录名一致比如你本地目录叫my-blog仓库也叫my-blog减少混乱。初始化仓库的时候我一般建议不勾选“Add a README file”因为本地项目已经有一堆文件了直接关联远程仓库再push就行避免先在云端生成一个README后再本地拉取合并这多余步骤。3.2 本地项目关联远程仓库并推送源代码在本地终端里进入项目根目录执行git init git add . git commit -m 首次提交 git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main这里有个小细节git branch -M main是必要的因为有些Git版本默认分支名是master而GitHub仓库默认分支是main两边分支名不一致会导致推送麻烦。统一成main就少了这个坑。推送时如果提示需要登录一般有两条路一是用Personal Access Token替代密码二是用SSH方式。我个人推荐SSH方式配置好之后免密推送非常顺手。如果暂时走Token也没关系只是后续每90天可能要重新生成一次。推送完成后打开GitHub仓库页面能看到源码文件已经上去了但这会儿仓库的Pages功能还没配置访问https://用户名.github.io/仓库名/大概率是404或者README展示页。别急下一步才是关键。3.3 编写GitHub Actions工作流云端自动构建与发布GitHub Actions是GitHub自带的CI/CD服务我们用它来监听main分支的push事件然后自动拉代码、装Hugo、构建站点、把生成的public目录发布到Pages服务上。在项目根目录下创建文件夹.github/workflows然后新建一个文件名字随意我习惯叫hugo-deploy.yml。文件内容如下name: Deploy Hugo site to Pages on: push: branches: - main workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugov3 with: hugo-version: latest extended: true - name: Build run: hugo --minify - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: ./public deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy id: deployment uses: actions/deploy-pagesv4这一套配置我从多个项目里实际用过整体很稳。下面逐个解释关键点避免你只是“抄了但不懂”第一on.push.branches指定了只有main分支收到push时才触发构建。如果你用的是master分支这里要改成master。第二permissions段里给pages: write和id-token: write是必须的这是新版Pages部署的要求不给权限会提示“Permission denied”。第三peaceiris/actions-hugov3是社区里常用的Hugo安装Actionextended: true对应安装Extended版hugo-version: latest意思是用最新版。如果你怕最新版不稳定可以写死一个版本号比如0.125.0。第四hugo --minify会在构建时压缩HTML和CSS减少体积提升访问速度。如果你的主题有特殊需要可以不加--minify但多数情况加了没问题。第五upload-pages-artifact和deploy-pages这两个Action是GitHub官方提供的Pages部署通道会把构建好的静态文件上传到Pages的Artifact再由deploy任务发布出去。整个流程分成build和deploy两个job前一个负责构建后一个负责发布彼此通过needs: build建立依赖关系。注意如果仓库主题是用git submodule引入的那Checkout步骤必须加上submodules: true否则Actions拉代码时只拉主仓库主题目录是空的构建必然失败。3.4 推送触发构建验证工作流是否跑通把工作流文件提交并推送git add .github/workflows/hugo-deploy.yml git commit -m 添加GitHub Actions部署工作流 git push origin main推送完成后打开仓库的“Actions”标签页你应该能看到一个名为Deploy Hugo site to Pages的workflow正在运行。第一次运行可能需要一两分钟因为要下载依赖的Action和Hugo二进制。等两个job都变成绿色对勾后回到仓库的“Settings - Pages”页面你会看到一行“Active”的提示下面会显示站点URL。这时用浏览器访问那个URL如果能看到你的文章页面部署就成功了。如果Actions日志里有红色报错点进对应的step就能看到具体日志。别慌日志里写得很清楚常见的就是Hugo版本问题、子模块没拉取、YAML格式错误这几种我后面专门列一个排查表。3.5 手动触发与日常更新流程配置完Actions之后日常更新文章就非常简单了。本地新建文章、预览、push云端自动完成全部部署hugo new posts/my-new-post.md # 编辑文章内容 git add . git commit -m 新增一篇文章 git push origin main如果某次构建失败了但你不想改代码只想重新跑一次构建可以在Actions页面里点击“Run workflow”按钮手动触发。我有时候修完bug懒得push测试就会用这个按钮验证配置算是一个小技巧。4. 自定义域名与HTTPS的完整接入过程4.1 在GitHub Pages上绑定自己的域名GitHub Pages默认分配的域名是用户名.github.io但很多人有自己的域名想挂在自己的域名下面比如blog.example.com。这个过程也不复杂但需要你同时操作DNS服务商和GitHub两个地方。第一步在GitHub仓库的“Settings - Pages”页面里找到“Custom domain”输入框填上你的域名点Save。GitHub会尝试自动创建CNAME文件。第二步去你的DNS服务商后台添加一条解析记录。多数情况下是CNAME类型主机记录填你想要的子域比如blog记录值填用户名.github.io。如果你的服务商不支持CNAME到根域名可以考虑用A记录指向GitHub Pages的IP但这个方案不推荐因为GitHub的IP可能会变。DNS解析生效需要时间短则几分钟长则几小时。生效的判断方式很简单在终端执行ping blog.example.com看是否解析到GitHub的IP。4.2 让HTTPS证书自动生效的注意事项Github Pages对于自定义域名会自动申请和续期HTTPS证书。但你需要在Pages设置里看到“Enforce HTTPS”的勾选框勾选上之后才能强制跳转HTTPS。这里有一个非常常见的坑如果你在DNS后台同时配置了其他服务比如用了同一个域名的主站可能会因为主机的CNAME冲突导致解析不生效。所以建议单独给博客开一个子域名不要和主站域名混用能省掉一大堆麻烦。另外一个坑是如果你在某个仓库配置了自定义域名这个域名会被记录在这个仓库的CNAME文件里。你如果删除这个仓库或者换仓库部署记得先在旧仓库的Pages设置里把自定义域名移除否则新仓库可能无法正常绑定。4.3 CNAME文件被覆盖的问题有时你在Pages设置里填了自定义域名GitHub会自动在仓库根目录生成一个CNAME文件里面就是你的域名文本。但在自动化部署流程里如果你直接把本地生成的public目录推送到仓库某个分支然后这个分支正好是Pages发布分支那每次部署都会用public覆盖仓库根目录GitHub自动创建的CNAME文件就会不见了。解决方案是把CNAME文件放在Hugo的static目录下这样每次构建时Hugo会把static里面的文件原样复制到public目录部署出去之后CNAME文件永远都在。这一点很多人想不到实际项目里非常实用。5. 常见问题与排查技巧实录5.1 线上纯白页面先查baseURL和资源引用路径这是所有Hugo部署问题里出现频率最高的。现象是本地预览完美线上页面能打开但所有样式、图片、脚本全部失效整个页面就像没有穿衣服一样。排查步骤按顺序来打开线上页面的浏览器控制台F12看Network标签下CSS和JS请求的URL。如果URL是https://用户名.github.io/仓库名/css/style.css这种带正确仓库名前缀的说明baseURL没问题如果URL变成https://用户名.github.io/css/style.css或者直接是/css/style.css说明baseURL少写了仓库名或结尾斜杠。修改hugo.toml里的baseURL重新push等Actions跑完再刷新看。这个问题之所以常见是因为很多人本地预览时Hugo的预览服务器会自动处理baseURL即使配置错了本地看起来也正常但线上环境是直接把文件放在服务器子路径下的没有baseURL前缀就找不到资源。5.2 Actions构建失败三类报错速查报错现象原因分析解决办法Traceback或某些Go依赖错误本地和云端Hugo版本不一致在workflow里固定hugo-version主题目录为空构建产物缺页面主题以submodule引入但未拉取Checkout步骤加submodules: trueYAML缩进错误、键值格式问题手写workflow时格式不标准用VS Code装YAML插件校验格式在实际项目里我遇到最诡异的一次是workflow跑得好好的某天突然开始全部失败日志提示某个Action的v版本获取不到。后来发现是第三方Action的原作者更新了版本策略旧版本被下线了。解决方式很简单把Action的版本从v2改成v3问题立刻消失。这也是我建议你尽量使用官方Action的原因比如actions/checkout、actions/upload-pages-artifact、actions/deploy-pages它们的维护频率高社区用户多生命周期有保障。5.3 部署成功但页面还是404这个情况也有两种细分一是部署成功但访问根路径404二是部署成功但访问子路径404。如果是第一种先确认你是否创建了public目录上传而不是把HTML文件直接散在仓库根目录。用Actions部署的话upload-pages-artifact里的path必须指向./public如果你写成了./会把整个仓库源码一起上传部署结构就乱了可能访问不了。如果是第二种大概率是baseURL的仓库名前缀没写对。项目主页的发布地址是https://用户名.github.io/仓库名/如果你访问的是https://用户名.github.io/仓库名少斜杠或直接https://用户名.github.io/GitHub可能给你返回404。GitHub Pages对这种路径的处理非常严格斜杠都不能错。5.4 自定义域名下HTTPS证书一直不生效这种坑通常是DNS解析配置的问题尤其是你用了CDN加速或域名托管服务商的“URL转发”功能时。GitHub Pages要求自定义域名必须能解析到它的服务器地址如果你的解析记录是指向某台代理服务器的那证书签发就一直不会成功。处理办法确认你用的解析类型是CNAME并且目标地址是用户名.github.io不要加https://前缀不要做任何转发。如果已经等了很久还是不行试着清一遍本地DNS缓存再用https://check-host.net这类工具从多个节点检测解析结果。5.5 本地无法预览端口冲突与草稿渲染有时候本地hugo server -D启动后浏览器打不开localhost:1313原因可能是端口被其他程序占用。你可以换端口启动hugo server -D -p 8080这会在8080端口启动预览。如果你发现自己新写的文章在预览里看不到先确认front matter里有没有draft: true。有的话启动命令里必须带-D参数才显示草稿这个机制是Hugo默认的不是bug。6. 我个人踩坑经验里的几个实用心得经历几轮折腾之后有几个经验是真心想分享给正在看这篇文章的人的。第一给Hugo配版本号管理是值得的。用Actions部署时workflow里写死一个你验证过的Hugo版本别用latest。不是因为最新版不好而是主题作者不会及时适配新版本某些API一改你的站点可能突然构建失败而你毫不知情。固定版本后除非你主动更新否则一直都不会出问题。第二静态文件别乱放。Hugo里有个static目录你放进去的东西会被原样复制到构建输出目录。CNAME文件、favicon.ico、robots.txt这些必须存在于站点根目录的文件都可以放在static下让构建流程替你处理就不会出现“每次部署后某个文件被覆盖”的情况。第三无论何时先确认本地构建输出再谈部署。Hugo有个好处构建产物就在本地public目录你可以直接双击打开里面的index.html看效果。这一步能帮你把绝大多数baseURL问题、资源路径问题拦截在部署之前而不用反复push等Actions结果省下的时间非常可观。第四如果页面样式正常但某些图片加载不出来先看图片文件是否被提交到了仓库。很多人用的图片管理方式是“引用网络图片URL”部署后没问题但如果你是本地图片放在static/images下提交时要把文件也一并提交不然云端构建出来的站点根本引不到这些图。第五日志是最好的老师。Actions失败时日志里每一行都有信息量。不要把日志关掉直接找百度先自己看一遍很多问题的答案就在报错信息里。比如“hugo: not found”说明Hugo没装成功“module not found”说明主题没拉下来“permission denied”通常和permissions配置有关。排查这些比盲目试别人的方案要高效得多。现在回想起来部署Hugo到GitHub Pages这件事最大的门槛其实不在技术而在“理解整个链条里每个环节扮演什么角色”。本地预览只是让你看到内容是什么样的线上部署则是另一套从代码到静态文件再到公网访问的流水线。搞清楚这条流水线的每个环节出了问题自然就知道该去哪里查。如果这篇文章能帮你少走几步弯路那我觉得这些折腾就都值了。