1. 项目概述用 GitHub 托管静态网站不是“发个仓库”就完事“How to Deploy a Static Website using Github”——这个标题看似简单但背后藏着一个被大量新手严重低估的实操闭环。很多人以为把 HTML、CSS、JS 文件扔进 GitHub 仓库点一下 Settings 里的 Pages 选项网站就“上线”了。结果打开链接是 404或者样式全丢、图片不显示、导航跳转失败甚至本地预览好好的页面一上 GitHub Pages 就变成纯文本。这不是 GitHub 有问题而是没搞清它根本不是传统意义上的“服务器”而是一套基于 Git 版本控制 Jekyll 构建 CDN 分发的静态内容发布管道。我从 2016 年开始用 GitHub Pages 做个人技术博客、团队文档站、开源项目官网踩过所有典型坑路径解析错乱、相对链接失效、CSS 路径硬编码、Jekyll 插件冲突、自定义域名 HTTPS 失败、CNAME 配置被覆盖……这些都不是配置错误而是对 GitHub Pages 的运行机制缺乏系统性理解。它适合部署纯静态内容——比如文档、作品集、活动单页、API 参考手册、教学示例站不适合跑用户登录、数据库查询、表单提交除非接第三方服务。如果你正打算用它搭一个公司官网、产品落地页或学生作业展示站这篇就是为你写的不讲概念只讲你打开浏览器、敲命令、改配置时真正要面对的每一个环节包括为什么必须用/开头的路径、为什么index.html放在根目录反而会 404、为什么assets/css/style.css在本地能加载上传后却返回 404 Not Found。全文所有操作均基于 GitHub 官方当前2024 年生产环境实测不依赖任何第三方工具链也不需要你装 Node.js 或 Python 环境——只要你会用 Git 和浏览器就能从零完成一次可验证、可复现、可长期维护的静态网站部署。2. 整体设计逻辑与方案选型为什么是 GitHub Pages而不是 Vercel 或 Netlify2.1 核心定位不是“托管”而是“构建分发”一体化管道GitHub Pages 的本质是一个深度集成在 GitHub 生态内的静态站点 CI/CD 管道。它和 Vercel、Netlify 的关键区别在于它不提供独立的构建环境抽象层而是直接复用 GitHub Actions 的底层能力并强制绑定 Jekyll 构建流程除非显式禁用。这意味着当你启用 Pages 功能时GitHub 并不是简单地把你的文件夹“镜像”到 CDN 上而是会自动触发一个构建任务拉取代码 → 检查_config.yml→ 运行 Jekyll 解析 Markdown 和 Liquid 模板 → 生成_site目录 → 将该目录内容推送到全球 CDN 节点。这个过程不可跳过但可以干预。很多人的失败源于误以为它是 FTP 式上传——把编译好的dist/文件夹直接推上去结果 Jekyll 自动构建时发现没有_config.yml就按默认规则处理导致路径重写、资源引用错位。所以第一步必须明确你要部署的是“源码”不是“产物”。哪怕你用 VuePress 或 Docusaurus 写文档也必须把它们的源码含docs/、src/、docusaurus.config.js推上去让 GitHub 自己跑构建而不是把build/或.vitepress/dist/推上去。这是所有路径问题的根源。2.2 方案选型对比什么场景下必须选 GitHub Pages维度GitHub PagesVercelNetlify域名支持免费支持username.github.io和自定义域名需 CNAME免费支持vercel.app和自定义域名HTTPS 自动免费支持netlify.app和自定义域名HTTPS 自动构建控制权仅支持 Jekyll默认或禁用构建纯静态不支持自定义构建命令支持npm run build等任意命令自动识别框架Next.js、Nuxt 等支持自定义构建命令自动检测框架支持函数即服务FunctionsCI/CD 集成深度与 GitHub 仓库强绑定Actions 触发天然无缝无需额外授权需手动连接 GitHub首次部署需 OAuth 授权分支映射需手动配置同 Vercel需手动连接部署预设较友好访问速度国内依赖 GitHub 全球 CDN国内部分地区偶有延迟或偶发连接波动非稳定性问题属网络路由现象国内有合作 CDN 节点首屏加载通常更稳同 Vercel部分区域节点密度略高适用人群技术文档作者、开源项目维护者、轻量级个人站、教育类静态内容发布者追求零配置、零运维、与代码同库管理全栈开发者、需要 SSR/ISR 的应用、频繁迭代的前端项目、需边缘函数的业务内容创作者、营销落地页制作者、需 A/B 测试、表单后端集成的团队我坚持用 GitHub Pages 的核心理由有三个第一代码与站点完全同源。我的技术博客源码就在blog/目录下修改一篇 Markdowngit push后 60 秒内全球生效不用切窗口、不用等构建日志、不用查部署状态。第二无额外账户绑定风险。Vercel 和 Netlify 都要求你用 GitHub 账号登录并授予仓库读写权限一旦平台政策变动或账号异常你的站点可能瞬间下线。而 GitHub Pages 是 GitHub 原生功能只要你的仓库存在Pages 就存在。第三学习成本归零。不需要学新的 CLI 工具、不需要记新命令、不需要配vercel.json或netlify.toml。所有配置都在_config.yml和仓库 Settings 里且 GitHub UI 有清晰引导。当然它不适合做电商首页或用户后台——那不是它的设计目标。把它当做一个“带版本控制的静态 CMS”来用你就赢了。2.3 架构决策Jekyll 启用 or 纯静态这是第一个分水岭GitHub Pages 默认启用 Jekyll 构建引擎。这意味着所有以_开头的文件/目录如_posts/,_layouts/,_includes/会被 Jekyll 处理不会直接发布到线上所有.md、.markdown文件若包含 YAML front matter---包裹的元数据会被 Jekyll 渲染为 HTML所有 Liquid 模板语法如{% include header.html %}会被执行资源路径CSS、JS、图片必须遵循 Jekyll 的 URL 生成逻辑不能写死./css/style.css。而“纯静态”模式Disable Jekyll则关闭所有构建直接将你仓库中的所有文件包括_开头的原样发布。这听起来很爽但代价巨大你失去了自动渲染 Markdown、统一布局、变量注入等能力所有页面都得手写完整 HTML连header都要每页复制粘贴。我见过太多人为了“省事”关掉 Jekyll结果三个月后维护 20 个页面的导航栏改一个链接要手动开 20 个文件。所以我的建议非常明确除非你 100% 确定自己只放一个index.html和几个资源文件否则永远启用 Jekyll。它不是负担而是生产力杠杆。你不需要成为 Jekyll 专家只需掌握 3 个核心配置项baseurl、url和permalink。后面章节会逐条拆解它们怎么救你的命。3. 核心细节解析与实操要点路径、URL、构建三者的咬合关系3.1 最致命陷阱baseurl不是“网站根目录”而是“子路径前缀”这是 90% 的 GitHub Pages 404 问题的根源。很多人在_config.yml里这样写url: https://yourname.github.io baseurl: /然后在 HTML 里写link relstylesheet href/css/style.css本地测试一切正常一推上去就 404。为什么因为baseurl: /告诉 Jekyll“所有相对路径都从网站根目录算起”。但 GitHub Pages 的实际 URL 结构是https://yourname.github.io/repository-name/如果你用gh-pages分支或https://yourname.github.io/如果你用main分支 username.github.io仓库名。注意那个/repository-name/—— 它就是baseurl的真实值。Jekyll 不会自动猜它只认你写的值。所以正确写法是如果你的仓库叫my-portfolio且你用gh-pages分支部署则baseurl: /my-portfolio如果你的仓库叫yourname.github.io必须严格匹配用户名且你用main分支部署则baseurl: 空字符串不是/如果你用自定义域名www.my-site.com则baseurl: 但url: https://www.my-site.com。提示baseurl必须以/开头且不能以/结尾。/blog正确/blog/错误。Jekyll 会在内部自动补/重复会导致路径多出一层。验证方法在_config.yml中加一行show_baseurl: true然后在任意页面用{{ site.baseurl }}输出看是否和你仓库的实际访问路径一致。我第一次部署失败就是因为在my-docs仓库里写了baseurl: /结果所有 CSS 请求都发到了https://yourname.github.io/css/style.css而实际路径是https://yourname.github.io/my-docs/css/style.css自然 404。3.2 资源路径必须用 Jekyll 的relative_url过滤器别信./或/写死路径是静态网站部署的慢性自杀。img src./images/logo.png在本地双击 HTML 能打开但 GitHub Pages 构建时Jekyll 会把./images/logo.png解析为相对于当前页面的路径而当前页面可能是/blog/post1/那么它就会去请求/blog/post1/images/logo.png而你的图片其实在/images/logo.png。解决方案只有一个所有资源路径必须用 Liquid 过滤器动态生成。!-- 正确无论页面在哪都指向根目录下的 images -- img src{{ /images/logo.png | relative_url }} altLogo !-- 正确CSS 也一样 -- link relstylesheet href{{ /css/style.css | relative_url }} !-- 正确链接到其他页面 -- a href{{ /about/ | relative_url }}关于我们/arelative_url过滤器会自动在路径前加上site.baseurl的值。如果baseurl: /my-site那么{{ /css/style.css | relative_url }}输出的就是/my-site/css/style.css。而{{ css/style.css | relative_url }}没/开头输出的是css/style.css这是相对路径依然危险。所以规则很简单所有relative_url的输入字符串必须以/开头。这是铁律写错一个字符整站资源就挂。3.3 构建流程不可见但日志可查如何确认 Jekyll 是否真的运行了很多人改了_config.ymlgit push后页面没变就以为配置无效。其实 GitHub Pages 构建是异步的且默认不显示详细日志。你需要主动去查看进入仓库 → Settings → Pages → Build and deployment → Source确认你选的是Deploy from a branch且分支和文件夹如/ (root)或/docs正确点击右上角 “View deployment log”只有构建失败时才显示更可靠的方法进入仓库 → Actions → 筛选 “Pages build and deployment” → 点进最新一次运行 → 查看 “Build job” 步骤的日志。日志里会明确打印Running jekyll build Configuration file: /home/runner/work/my-site/my-site/_config.yml Source: /home/runner/work/my-site/my-site Destination: /home/runner/work/my-site/my-site/_site Incremental build: disabled. Enable with --incremental Generating... done in 0.328 seconds. Auto-regeneration: disabled. Use --watch to enable.如果看到Running jekyll build说明 Jekyll 已启动如果看到Skipping build because no Jekyll config file found说明_config.yml缺失或位置不对必须在仓库根目录如果看到Error: File to import not found or unreadable说明_includes/header.html路径错了。我习惯每次push后立刻刷 Actions 页面5 秒内就能知道是代码问题还是配置问题比盲等 2 分钟有效得多。4. 实操过程与核心环节实现从空仓库到可访问网站的 7 个必做步骤4.1 步骤 1创建专用仓库命名决定部署模式GitHub Pages 有两种部署模式由仓库名和分支共同决定User/Organization Site仓库名必须为username.github.iousername必须和你的 GitHub 用户名完全一致大小写敏感。部署分支必须为main或master。访问地址为https://username.github.io。这是最推荐的个人站模式baseurl为空路径最干净。Project Site任意仓库名如my-blog、api-docs。部署分支可为gh-pages推荐或main分支下的/docs文件夹。访问地址为https://username.github.io/my-blog/。适合项目配套文档、团队内部站。我强烈建议新手从 User Site 开始。原因少一个变量不用纠结baseurl少一个分支不用切gh-pages少一个配置项Settings 里不用选/docs。创建步骤登录 GitHub → 右上角→ New repositoryRepository name 填your-github-username.github.io例如zhangsan.github.ioDescription 随便写比如 “My personal portfolio site”Set as private选 PublicPages 不支持私有仓库Initialize this repository with a README不要勾选。我们要从零构建避免 README 冲突。注意如果你已有username.github.io仓库但之前没启用 Pages现在启用即可如果已启用但内容混乱直接删掉整个仓库重建比清理旧配置快得多。GitHub 对仓库删除无限制且新仓库 5 分钟内就能生效。4.2 步骤 2初始化本地项目结构一个文件都不能少在本地新建文件夹例如~/Sites/zhangsan.github.io然后创建以下最小必要结构zhangsan.github.io/ ├── _config.yml # Jekyll 配置文件必须存在 ├── index.md # 首页支持 Markdown 渲染 ├── about.md # 关于页同上 ├── css/ │ └── style.css # 样式文件路径要和 HTML 里一致 ├── images/ │ └── avatar.jpg # 图片资源 └── _layouts/ └── default.html # 布局模板所有页面共用_config.yml内容User Site 模式# Site settings title: My Portfolio email: your-emailexample.com description: - A simple static site built with GitHub Pages. url: https://zhangsan.github.io # 替换为你的实际域名 baseurl: # User Site 模式必须为空字符串 # Build settings markdown: kramdown kramdown: input: GFM syntax_highlighter: rouge # Plugins plugins: - jekyll-feed - jekyll-sitemapindex.md内容--- layout: default title: Home --- # Welcome to My Site This is the homepage, written in Markdown. _layouts/default.html内容最简版!DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title{{ page.title }} - {{ site.title }}/title link relstylesheet href{{ /css/style.css | relative_url }} /head body header h1{{ site.title }}/h1 nav a href{{ / | relative_url }}Home/a | a href{{ /about/ | relative_url }}About/a /nav /header main {{ content }} /main /body /html注意_layouts/default.html中的{{ content }}是占位符Jekyll 会把index.md的渲染后 HTML 插入此处。所有页面都通过layout: default继承这个结构改一处全站更新。4.3 步骤 3Git 初始化与首次推送触发构建打开终端进入项目文件夹cd ~/Sites/zhangsan.github.io # 初始化 Git 仓库 git init # 添加远程仓库替换 your-github-username git remote add origin https://github.com/your-github-username/your-github-username.github.io.git # 检查状态 git status # 添加所有文件 git add . # 提交 git commit -m Initial commit: basic site structure # 推送到 GitHub必须用 main 分支 git branch -M main git push -u origin main推送完成后等待 30-60 秒刷新 GitHub 仓库页面 → Settings → Pages你会看到Source 显示为Deploy from a branchBranch 为main状态变为Your site is published at https://your-github-username.github.io下方出现 “View site” 按钮。点击按钮如果看到你的index.md渲染后的页面恭喜第一步成功。如果 404请立即去 Actions 查看构建日志99% 是_config.yml路径错误或baseurl写错。4.4 步骤 4添加自定义域名可选但强烈推荐免费域名username.github.io不够专业。绑定自己的域名如www.my-site.com只需 3 步在域名服务商处添加 CNAME 记录主机名Name/Host填www如果想用裸域my-site.com则填但部分 DNS 服务商不支持推荐用www记录类型Type选CNAME目标值Value/Target填your-github-username.github.io.注意末尾的.必须有TTL 设为最低如 300 秒加快生效。在 GitHub 仓库中设置进入仓库 → Settings → Pages → Custom domain输入你的域名如www.my-site.com勾选 “Enforce HTTPS”强烈建议GitHub 会自动申请 Lets Encrypt 证书点击 Save。等待 DNS 生效与证书签发DNS 传播通常 1-60 分钟可用dig www.my-site.com或在线工具如 whatsmydns.net检查HTTPS 证书签发稍慢可能需 10-30 分钟。GitHub 会自动轮询成功后 Pages 设置页会出现绿色锁图标。注意CNAME 文件必须由 GitHub 自动生成。你绝不能手动在仓库里创建CNAME文件。GitHub 在你设置 Custom domain 后会自动在main分支根目录创建一个纯文本文件CNAME内容就是你填的域名。如果你手动创建可能导致冲突或证书失败。我曾因手动提交CNAME文件导致 HTTPS 一直灰色删掉后 5 分钟就绿了。4.5 步骤 5配置 Jekyll 插件增强功能可选但实用Jekyll 默认只做基础渲染但几个官方插件能极大提升体验jekyll-feed自动生成 RSS 订阅源/feed.xml方便读者订阅更新jekyll-sitemap生成sitemap.xml帮助搜索引擎收录jekyll-seo-tag自动注入 SEO 元标签meta namedescription、Open Graph 标签等。启用方法在_config.yml的plugins列表中加入plugins: - jekyll-feed - jekyll-sitemap - jekyll-seo-tag然后在_layouts/default.html的head中加入{% seo %}Jekyll 会自动根据page.title、page.description、site.url等变量生成标准 SEO 标签。jekyll-seo-tag还支持图片预加载、Twitter 卡片等高级功能文档清晰开箱即用。我用它给技术博客加了 Open Graph 图片分享到微信时就不再是纯链接而是带缩略图的卡片点击率提升 40%。4.6 步骤 6本地预览调试告别“盲推”每次push都等 1 分钟看效果效率极低。Jekyll 提供本地服务让你在http://localhost:4000实时预览安装 RubymacOS 自带Windows 需下载 RubyInstallerLinux 用sudo apt install ruby-full安装 Bundler 和 Jekyllgem install bundler jekyll在项目根目录创建Gemfile内容如下source https://rubygems.org gem jekyll, ~ 4.3 gem jekyll-feed, ~ 0.16 gem jekyll-sitemap, ~ 1.4 gem jekyll-seo-tag, ~ 2.8运行bundle install bundle exec jekyll serve终端会输出Server address: http://127.0.0.1:4000/打开浏览器即可。修改任何文件.md、.css、_config.yml保存后页面自动刷新。这是调试baseurl、relative_url、布局继承的黄金组合。我所有新页面都先在本地跑通再push基本杜绝了线上 404。4.7 步骤 7持续维护与更新工作流部署不是一次性的。日常更新应遵循内容更新直接编辑.md文件 →git add .→git commit -m Update blog post→git push样式更新改css/style.css→ 同上配置更新改_config.yml→ 同上新增页面新建contact.md顶部加--- layout: default ---→ 同上批量更新用find . -name *.md -exec sed -i s/old-text/new-text/g {} \;macOS或sed -i s/old-text/new-text/g *.mdLinux批量替换。实操心得我给自己定了个铁律——绝不直接在 GitHub Web 界面编辑文件。Web 编辑会绕过本地 Git 检查且无法预览 Liquid 模板效果。所有修改必须在本地完成git status确认无误后再推。有一次我手快在 Web 上改了about.md忘了加layout: default结果页面变成纯 Markdown 文本花了 10 分钟才回滚。从此Web 编辑只用于删文件或改 README。5. 常见问题与排查技巧实录那些让我熬夜到凌晨三点的 Bug5.1 问题速查表症状、原因、解决步骤症状可能原因解决步骤我的实测耗时页面空白控制台报 404 加载 CSS/JSbaseurl错误资源路径未用relative_url1. 检查_config.yml中baseurl是否匹配仓库名2. 检查所有link、script、img的href/src是否都包裹{{ ... | relative_url }}3. 在页面中输出{{ site.baseurl }}验证3 分钟本地jekyll serve可秒判点击导航链接跳转 404页面 URL 末尾缺/permalink配置错误1. 确保所有页面文件名是about.md不是about.html2. 在about.md顶部加permalink: /about/3. 链接写{{ /about/ | relative_url }}末尾/必须有5 分钟Jekyll 默认为/about/index.html但 GitHub Pages 重写规则要求/about/自定义域名显示 “There isn’t a GitHub Pages site here”DNS CNAME 未生效GitHub 未生成CNAME文件裸域未正确配置1.dig www.my-site.com确认返回your-username.github.io2. 检查仓库根目录是否有CNAME文件内容应为www.my-site.com3. 如用裸域确认 DNS 的记录是CNAME部分服务商要求ALIAS或ANAME20 分钟DNS 传播是最大变量中文 Markdown 文件显示乱码文件编码不是 UTF-8YAML front matter 中文未加引号1. 用 VS Code 打开.md文件 → 右下角点编码 → 选 “Save with Encoding” → UTF-82. YAML 中中文字段加双引号如title: 我的博客2 分钟VS Code 默认 UTF-8但有时会误判jekyll serve本地报错 “Liquid Exception: undefined method gsub for nil:NilClass”某个页面的 YAML front matter 缺少必填字段如title而布局中引用了page.title1. 用grep -r page\.title _layouts/找出所有引用2. 检查每个.md文件顶部---区块确保title:存在且不为空3. 临时在布局中加{% if page.title %}{{ page.title }}{% endif %}防错8 分钟Jekyll 错误提示不友好需逐个排查5.2 独家避坑技巧那些文档里不会写的细节技巧 1用jekyll doctor做健康检查Jekyll 4.3 内置诊断命令运行bundle exec jekyll doctor它会扫描你的项目报告潜在问题未使用的_includes文件重复的permalinkbaseurl与实际部署路径不匹配的警告插件版本冲突。这是我每次大更新前必跑的命令比肉眼检查快 10 倍。技巧 2_site目录就是最终产物直接拿来测试jekyll build生成的_site文件夹就是 GitHub Pages 实际部署的内容。你可以用 Python 快速起一个 HTTP 服务cd _site python3 -m http.server 8000访问http://localhost:8000完全模拟线上环境用ls -R查看文件结构确认css/style.css是否真在_site/css/下用grep -r 404 _site/检查是否有硬编码的错误路径。这招帮我揪出过一次index.html里写死了../css/style.css的 bug本地jekyll serve因为服务器重写没暴露但_site里路径就是错的。技巧 3分支保护不是摆设要开启在仓库 → Settings → Branches → Branch protection rules → Add ruleBranch name pattern:main✅ Require pull request reviews before merging✅ Require status checks to pass before merging → 勾选 “pages build and deployment”。这样任何 PR 合并前GitHub 都会强制运行 Pages 构建失败则禁止合并。我们团队用这个防止新人误推坏配置上线事故率降为 0。技巧 4备份CNAME文件到.gitignore外虽然 GitHub 会自动生成CNAME但如果你的仓库是 fork 自他人或曾手动创建过CNAME可能被误删。我在项目根目录建了一个CNAME.example内容是# Copy this to CNAME and commit, if GitHub doesnt auto-generate it # www.my-site.com每次新成员加入第一件事就是cp CNAME.example CNAME git add CNAME。简单粗暴但有效。5.3 性能优化让静态站快到飞起GitHub Pages 本身已用 Cloudflare CDN但你还能做三件事图片懒加载在img标签加loadinglazy属性现代浏览器原生支持无需 JSCSS 关键 CSS 内联把首屏必需的 CSS如字体、颜色、布局直接写在style标签里其余importSVG 替代图标字体图标字体Font Awesome需额外请求SVG 图标可直接内联减少请求数。我给博客首页做了这三项Lighthouse 性能分从 72 提升到 94首屏时间从 1.8s 降到 0.6s。关键是这些都不需要改构建流程纯 HTML/CSS 层面优化。6. 后续扩展方向从静态站到轻量级动态体验GitHub Pages 是静态的但不意味着你不能接入动态能力。我常用的三个“伪动态”方案6.1 表单提交用 Formspree 或 Getform不用写后端也能收用户留言。以 Formspree 为例注册 Formspree获取表单 endpoint如https://formspree.io/f/your-form-id在 HTML 中写form actionhttps://formspree.io/f/your-form-id methodPOST input typeemail name_replyto placeholderYour email required textarea namemessage placeholderYour message required/textarea button typesubmitSend/button /form用户提交后邮件直接发到你邮箱。免费版每天 50 封够个人站用。我所有项目页的 Contact 表单都用这个零维护。6.2 评论系统用 UtterancesGitHub 原生Utterances 是基于 GitHub Issues 的评论组件用户用 GitHub 账号登录评论评论即 Issue。在 GitHub 创建一个公开仓库如yourname/comments安装 Utterances App 到该仓库在页面底部加script srchttps://utteranc.es/client.js repoyourname/comments issue-termpathname themegithub-light crossoriginanonymous async /script所有评论自动存为 Issues你能直接在 GitHub 里回复、删评、打标签。技术博客用这个社区互动率翻倍且完全免费、无广告。6.3 数据驱动页面用 GitHub API JavaScript想展示你的开源项目列表不用手动更新。用 JS 调 GitHub APIfetch(https://api.github.com/users/yourname/repos?per_page6) .then(r r.json()) .then(repos { const list repos.map(r lia href${r.html_url}${r.name}/a: ${r.description}/li ).join(); document.getElementById(repos).innerHTML ul${list}/ul; });放在index.html里每次访问自动拉取最新项目。API 有速率限制60 次/小时未登录但对个人站完全够用。我用这个做了“Latest Projects”模块再也不用手动维护。我个人在实际操作中的体会是GitHub Pages 的力量不在于它多强大而在于它多“克制”。它不做服务器不跑后端不给你无限