1. 项目概述：用 GitHub Pages 零成本发布静态网站，我三年来部署过 87 个个人项目的真实路径

你有没有过这种时刻：花一晚上写完一个作品集页面、一个课程作业展示页、一个开源工具的说明站，甚至只是想把一份精心排版的简历发给 HR——结果卡在“怎么让别人点开就能看”这一步？买域名、配服务器、装 Nginx、搞 HTTPS……光是列出来就让人想关掉编辑器。其实，从你本地index.html文件双击打开那一刻起，到全世界任何人输入一个网址就能访问它，中间真正需要手动操作的，只有 6 分钟。这不是夸张，是我过去三年在高校教学、带学生做毕设、帮同事上线内部文档时反复验证过的路径：GitHub Pages 是目前对纯静态内容最省心、最稳定、最无需运维的公开托管方案。它不卖课、不推会员、不弹广告，背后就是 GitHub 自己的全球 CDN 节点网络，你提交一次代码，自动构建、自动缓存、自动 HTTPS，连证书续期都看不见。关键词里提到的Towards AI — Multidisciplinary Science Journal，正是大量科研者用它快速发布论文可视化 Demo、模型效果对比页、数据集介绍页的典型场景——没有后端、不碰数据库、不写 API，只靠 HTML/CSS/JS 就能跑通完整链路。这篇文章要讲的，不是“点击 Settings → GitHub Pages → 选 master branch”这个按钮流程，而是为什么必须用index.html命名、为什么仓库名决定 URL 结构、为什么文件夹层级一错整个站点就 404、以及当你发现页面空白、样式丢失、图片不显示时，到底该看哪一行日志、改哪一行路径。我会用一个真实部署失败的案例开场：上周帮一位生物信息学博士部署她的基因序列比对结果展示页，所有文件都传上去了，但打开链接只显示“404 Not Found”。问题出在她把style.css放进了assets/css/子目录，而 HTML 里写的却是<link rel="stylesheet" href="css/style.css">——这种路径错位，在本地双击打开时完全正常，一上 GitHub Pages 就崩。这就是本文要拆解的核心：静态网站托管不是“上传即完成”，而是“结构即逻辑”。适合谁读？刚学完 HTML 的大学生、想快速上线作品集的设计师、需要分享分析报告的数据分析师、还有像我一样常年和学生、同事、合作方打交道，必须在 10 分钟内给出可访问链接的技术支持者。你不需要懂 Git 命令行，但得愿意按步骤检查文件夹；你不需要会写 JavaScript，但得理解相对路径怎么算；你不需要租服务器，但得知道 GitHub Pages 的规则边界在哪里。

2. 核心设计逻辑与方案选型：为什么是 GitHub Pages，而不是其他方式？

2.1 两种部署模式的本质区别：username.github.iovsrepo-name

原文提到“Using Master Branch”和“Without using Master Branch”，这个表述容易引发误解。实际上，GitHub Pages 只有一种底层机制：从指定分支的指定目录中读取静态文件，并通过 GitHub 的 CDN 服务对外提供 HTTP 访问。所谓“两种方式”，本质是 URL 路径结构和仓库用途的差异，而非技术实现的不同。

第一种，username.github.io模式（官方称 User/Organization Pages）：

• 仓库名必须严格为[your-github-username].github.io（例如我的账号是zhangsan，仓库名必须是zhangsan.github.io）
• 默认从main或master分支的根目录读取文件（2020 年后 GitHub 默认分支已改为main，但 Pages 设置仍兼容master）
• 生成的 URL 是https://zhangsan.github.io/，没有子路径，直接对应根域名
• 关键限制：一个 GitHub 账号只能有一个这样的仓库。它天然适合作为你的“个人主页”或“主作品集门户”。

第二种，Project Pages 模式（即repo-name模式）：

• 仓库名可以是任意合法名称（如my-portfolio、># 1. 在本地创建文件夹并进入 mkdir my-portfolio && cd my-portfolio # 2. 初始化 Git 仓库 git init # 3. 创建基本文件（示例） echo "<h1>Hello World</h1>" > index.html # 4. 添加到暂存区 git add . # 5. 提交（commit） git commit -m "Initial commit: basic index.html" # 6. 添加远程仓库地址（替换为你自己的） git remote add origin https://github.com/zhangsan/my-portfolio.git # 7. 推送到 GitHub（首次推送用 -u） git push -u origin main

  命令行的好处是，git status可以随时查看哪些文件已添加、哪些未跟踪；git log可以回溯每次修改；最重要的是，它强制你理解“本地仓库”和“远程仓库”的关系，避免网页端上传时的模糊操作。

  结构校验的黄金法则：
  上传完成后，打开 GitHub 仓库页面，点击index.html文件。在文件内容上方，你会看到一串面包屑导航，例如：zhangsan / my-portfolio / index.html。这个路径，就是index.html在仓库中的绝对路径。现在，打开你的index.html，找到所有href和src属性：

  • <link rel="stylesheet" href="css/style.css">→ 这个路径，应该能从index.html的位置出发，“向下”进入css文件夹，找到style.css。
  • <img src="images/avatar.jpg">→ 同理，应该能“向下”进入images文件夹。
  • <a href="about.html">About</a>→ 这个about.html必须和index.html在同一级目录（都在根目录下）。

  如果about.html实际放在pages/about.html，那么链接必须写成<a href="pages/about.html">About</a>。路径不是猜的，是算出来的，起点就是当前 HTML 文件的位置。

  3.3 GitHub Pages 开启与配置：Settings 里的关键开关

  上传完文件，别急着点 Settings。先做一件事：等待 1-2 分钟。GitHub 的后台处理（尤其是 Pages 构建）需要时间，刚上传完立刻去 Settings，可能页面还没刷新，导致你看不到最新选项。

  开启 Pages 的精确步骤：

  • 在仓库页面，点击顶部导航栏的 “Settings”（不是右上角的 Settings）
  • 在左侧边栏，向下滚动，找到 “Pages” 选项（在 “Code and automation” 区域下），点击它
  • 在 “Source” 部分，你会看到三个选项：
    • Deploy from a branch（最常用）
    • Deploy from a folder（已弃用，忽略）
    • Build and deployment（用于 Jekyll 或自定义构建，新手跳过）
  • 选择Deploy from a branch
  • Branch：下拉菜单，选择main（如果你仓库默认分支是main）或master（如果旧仓库）。旁边会显示 “(default)” 字样，选那个就行。
  • Folder：下拉菜单，选择/ (root)。这是最关键的一步！它告诉 GitHub Pages：“请从这个分支的根目录（/）开始读取文件”。如果你的index.html就在根目录，就必须选/。只有当你把所有网站文件都放在docs/子目录下时，才选/docs。
  • 点击 “Save” 按钮

  此时，GitHub 会立即开始构建。页面会刷新，顶部出现一个黄色提示条：“Your site is ready to be published at https://zhangsan.github.io/my-portfolio/”。这个 URL 就是你的网站地址。但请注意：这个提示条出现，不代表网站已可访问。它只表示构建任务已启动。

  等待与验证：

  • 复制这个 URL，粘贴到新浏览器标签页，按 Enter。
  • 如果看到你的index.html内容，恭喜，成功了。
  • 如果看到 “404 Page not found”，别慌。这是最常见的情况，原因几乎总是：
    1. index.html不在根目录（比如你把它放进了src/或public/子目录）
    2. 仓库名拼写错误（比如my-portfolio写成了my-protfolio）
    3. 你选错了 Branch（比如仓库是main，你却选了master）
    4. 你选错了 Folder（比如index.html在根目录，你却选了/docs）

  注意：GitHub Pages 的构建日志（Build logs）在 “Settings → Pages” 页面底部，点击 “View build log” 可以看到详细过程。如果构建失败，日志里会明确写出错误，比如 “No index.html found in root directory”。这是最权威的诊断依据，比网上搜教程管用一百倍。

  3.4 域名与自定义：从github.io到你自己的域名

  GitHub Pages 默认提供username.github.io/repo-name的免费域名，这足够绝大多数场景。但如果你想用www.yourname.com或portfolio.yourcompany.com，GitHub 也支持绑定自定义域名，且完全免费（DNS 解析费用另算，但通常也是免费的）。

  绑定步骤（以www.myportfolio.com为例）：

  • 在你的域名注册商（如 GoDaddy、Namecheap、阿里云）后台，添加两条 DNS 记录：
    • 类型A，主机名www，值185.199.108.153（GitHub Pages 的 IP 地址，共四条，需全部添加：185.199.108.153,185.199.109.153,185.199.110.153,185.199.111.153）
    • 类型CNAME，主机名@，值zhangsan.github.io.（注意末尾的点）
  • 回到 GitHub 仓库 “Settings → Pages”，在 “Custom domain” 输入框，填入www.myportfolio.com，点击 “Save”。
  • GitHub 会自动生成一个CNAME文件（内容就是你的域名），并提交到你的仓库根目录。这个文件必须存在，且内容必须准确，否则 HTTPS 会失败。

  HTTPS 强制启用：
  GitHub Pages 会自动为你的github.io域名和自定义域名申请 Let's Encrypt 证书，并强制重定向 HTTP 到 HTTPS。你无需任何操作，也不用担心证书过期——GitHub 全权负责。这是它比很多廉价虚拟主机更省心的地方。

  4. 常见问题与实战排查：那些让我熬夜到凌晨三点的 Bug

  4.1 页面空白/404：结构、路径、分支的三重校验

  这是新手遭遇率 100% 的问题。症状：打开 URL，浏览器一片空白，或显示 “404 Page not found”。解决方案不是重做，而是按顺序排查：

  第一层：检查index.html是否在正确位置

  • 打开 GitHub 仓库，确认index.html文件直接列在文件列表最顶层，不在任何子文件夹里。
  • 如果它在src/index.html，那么你有两个选择：
    a) 把src/里的所有文件（包括index.html,css/,js/）剪切出来，粘贴到根目录；
    b) 在 “Settings → Pages” 里，把 Folder 从/ (root)改成/src。

  第二层：检查所有资源路径是否正确

  • 在浏览器打开你的网站 URL，按 F12 打开开发者工具，切换到 “Console” 标签页。
  • 刷新页面。Console 里会列出所有加载失败的资源，格式如：
    Failed to load resource: the server responded with a status of 404 ()
    下面跟着一个链接，比如https://zhangsan.github.io/my-portfolio/css/style.css。
  • 点击这个链接。如果浏览器显示 “404”，说明这个文件确实不存在。此时，回到 GitHub 仓库，按这个路径去找：
    • https://zhangsan.github.io/my-portfolio/css/style.css→ 应该对应仓库里的css/style.css文件。
    • 如果仓库里style.css实际在styles/style.css，那么你需要：
      • 修改index.html里的<link>标签，把href="css/style.css"改成href="styles/style.css"；
      • 或者，把styles/文件夹重命名为css/。

  第三层：检查分支和 Folder 设置是否匹配

  • 进入 “Settings → Pages”，确认 Branch 选的是你实际推送代码的分支（main还是master？）。
  • 确认 Folder 选的是/ (root)还是/docs，这必须和index.html的物理位置一致。
  • 一个快速验证法：在 GitHub 仓库页面，点击index.html，在地址栏 URL 末尾加上/，比如https://github.com/zhangsan/my-portfolio/blob/main/index.html→ 改成https://github.com/zhangsan/my-portfolio/blob/main/。如果这个 URL 能打开，说明index.html在main分支的根目录，设置就是对的。

  4.2 样式丢失/图片不显示：相对路径的陷阱与绝对路径的救赎

  症状：页面文字能显示，但全是黑体无样式，图片位置是破碎图标。Console 里一堆 404，指向 CSS 和图片文件。

  根本原因：相对路径计算错误。
  <link rel="stylesheet" href="css/style.css">这个路径，是相对于当前 HTML 文件的 URL 来计算的。

  • 当你在本地双击index.html，URL 是file:///Users/you/my-portfolio/index.html，css/style.css就是file:///Users/you/my-portfolio/css/style.css，没问题。
  • 但当index.html被 GitHub Pages 托管在https://zhangsan.github.io/my-portfolio/，这个 URL 的“当前路径”就是/my-portfolio/。所以href="css/style.css"会被浏览器解析为https://zhangsan.github.io/my-portfolio/css/style.css。

  如果这个路径在仓库里不存在，就 404。

  解决方案：

  • 首选：修正相对路径。确保 HTML 中的href和src路径，与 GitHub 仓库里的实际文件夹结构完全匹配。这是最规范、最易维护的做法。
  • 次选：使用绝对路径（仅限 GitHub Pages）。在index.html里，把href="css/style.css"改成href="/my-portfolio/css/style.css"（注意开头的/和仓库名）。这样，无论index.html在哪个子路径，都会从根域名开始找。但缺点是，这个路径硬编码了仓库名，如果你以后改名，所有路径都要改。
  • 终极方案：使用<base>标签。在index.html的<head>里，添加：

    <base href="https://zhangsan.github.io/my-portfolio/">

    这样，后面所有的相对路径（css/style.css,images/logo.png）都会自动加上这个前缀。但它会影响所有链接，需谨慎。

  4.3 更改内容后不更新：缓存与构建延迟

  症状：你修改了index.html，git push了，也看到 GitHub 上文件更新了，但打开网站还是旧内容。

  原因一：浏览器缓存
  浏览器为了速度，会缓存 HTML、CSS、JS 文件。解决方案：

  • 强制刷新：Windows/Linux 按Ctrl + F5，Mac 按Cmd + Shift + R。
  • 或者，在 Chrome 里按F12→ 右键 “Reload” → 选择 “Empty Cache and Hard Reload”。

  原因二：GitHub Pages 构建延迟
  GitHub Pages 的构建不是实时的。从你push代码，到新版本上线，通常需要 30 秒到 2 分钟。如果刚push就刷新，很可能看到的还是旧版本。耐心等待 2 分钟，再刷新。

  原因三：CDN 缓存（罕见）
  GitHub 使用 Cloudflare CDN，极少数情况下，CDN 节点缓存了旧版本。这时，你可以在 “Settings → Pages” 页面，点击 “Clear cache and redeploy site”（清除缓存并重新部署）。这个按钮在 “Build logs” 下方，有时需要滚动才能看到。

  4.4 中文乱码与特殊字符：编码与元标签的双重保障

  症状：网页标题、段落文字显示为方块或问号（）。

  原因：文件编码不统一。

  • 你的文本编辑器（如 VS Code）保存index.html时，可能用了GBK或ISO-8859-1编码，而浏览器默认用UTF-8解析，导致乱码。

  解决方案：

  • 编辑器设置：在 VS Code，右下角状态栏点击编码（如 “UTF-8” 或 “GBK”），选择 “Reopen with Encoding” → “UTF-8”。然后，点击 “Save with Encoding” → “UTF-8”。
  • HTML 元标签：在index.html的<head>里，确保有这行：

    <meta charset="UTF-8">

    这是告诉浏览器：“请用 UTF-8 编码来解析这个页面”。没有这行，浏览器会猜测编码，猜测失败就乱码。

  额外提醒：文件名不要用中文
  虽然 GitHub 支持中文文件名，但某些旧版浏览器或系统可能无法正确解析简历.html这样的文件名。为求最大兼容性，坚持用英文和短横线：resume.html。

  5. 进阶技巧与长期维护：让 GitHub Pages 成为你最可靠的数字地基

  5.1 版本控制与协作：多人编辑一个网站的正确姿势

  GitHub Pages 天然集成 Git，这不仅是备份，更是协作基石。想象一个课程小组项目：

  • A 同学负责写index.html和文案
  • B 同学负责设计css/style.css
  • C 同学负责制作images/里的图表

  他们不需要共享一个 FTP 密码，也不用互相发 ZIP 包。流程是：

  • 创建一个团队组织（Organization），邀请三人加入
  • 在组织下创建一个仓库cs101-final-project
  • 每人git clone到本地，各自修改自己负责的文件
  • git add→git commit→git push
  • GitHub Pages 自动构建最新main分支

  关键技巧：

  • 分支保护（Branch Protection）：在 “Settings → Branches” 里，为main分支启用保护。要求 PR（Pull Request）必须经过至少一人审查（Review）才能合并。这避免了某人误删index.html导致全站崩溃。
  • PR 描述模板：在仓库根目录创建.github/pull_request_template.md，内容预设：

    ## 描述 （请简述本次修改的目的） ## 修改内容 - [ ] 修改了 index.html 的标题 - [ ] 更新了 css/style.css 的颜色方案 - [ ] 替换了 images/logo.png

    这样，每次提交 PR，都会自动填充这个模板，确保修改可追溯。

  5.2 自动化部署：告别手动上传，拥抱 CI/CD

  当项目变大（比如加入 Markdown 写作、Sass 编译、图片压缩），手动上传就太原始了。GitHub Actions 可以帮你自动化一切。

  一个真实案例：我的博客
  我用 Hugo（一个静态网站生成器）写博客，源文件是 Markdown，需要编译成 HTML。我配置了一个 Action：

  • 每次向main分支push一个.md文件
  • Action 自动运行hugo命令，生成public/目录
  • 将public/目录的内容，自动推送到同一个仓库的gh-pages分支
  • GitHub Pages 从gh-pages分支读取，完成部署

  整个过程无需我手动操作，写完 Markdown，git push，5 分钟后新文章就上线了。配置文件.github/workflows/deploy.yml只有 20 行，网上有大量成熟模板可抄。

  5.3 安全与合规：静态网站的隐形责任

  GitHub Pages 是静态托管，不执行服务端代码，因此没有 SQL 注入、RCE（远程代码执行）等传统 Web 安全风险。但仍有两点必须注意：

  • 第三方资源安全：如果你在index.html里引入了<script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>，这个 jQuery 文件由 jsDelivr 提供。如果 jsDelivr 被黑，你的网站就会加载恶意脚本。解决方案：

    • 使用 Subresource Integrity（SRI）：在<script>标签里加上integrity属性，其值是 jQuery 文件的 SHA256 哈希值。浏览器会校验下载的文件是否与哈希值匹配，不匹配则拒绝执行。
    • 或者，把jquery.min.js下载下来，放到你的js/文件夹里，用相对路径引用。

  • 隐私合规（GDPR/CCPA）：如果你的网站嵌入了 Google Analytics、Facebook Pixel 等追踪代码，你需要：

    • 在网站上添加隐私政策链接
    • 实现 Cookie 同意横幅（Banner），用户点击“同意”后才加载追踪脚本
    • GitHub Pages 本身不存储用户数据，但你嵌入的第三方服务会。责任在你，不在 GitHub。

  我在实际使用中发现，最省心的长期策略是：把 GitHub Pages 当作“最终交付物”，而不是“开发环境”。所有设计、写作、调试，都在本地完成；GitHub 只是那个安静、可靠、永不宕机的发布渠道。它不抢你的风头，不加你的广告，不改你的代码，只是忠实地把你写的index.html，变成全世界都能访问的一个 URL。这种纯粹，恰恰是它历经十年依然不可替代的原因。