GitHub Pages 必须显式启用并配置发布源才能生效，不能仅靠上传index.html；个人站点需用username.github.io命名仓库且放main分支根目录，项目站点则需在Settings→Pages中指定分支和文件夹，否则将返回404或显示代码浏览页。
GitHub Pages 要求仓库名或路径符合特定格式
直接把 index.html 丢进任意 GitHub 仓库根目录，不会自动变成可访问的网页——GitHub Pages 不会扫描整个仓库去“找” index.html。它只在你明确启用并配置好发布源后，才从指定位置（如 main 分支的 / 或 /docs 目录）读取文件。
常见错误现象：404 Page not found，或者页面打开是 GitHub 的代码浏览界面，而不是渲染后的 HTML。
- 个人/组织账户必须用
username.github.io这种仓库名（username替换为你的 GitHub 用户名），且内容放在main分支根目录 - 普通项目仓库可以启用 Pages，但默认发布源是
main分支的/ (root)或/docs目录，选错就找不到index.html - 如果仓库是私有的，GitHub Pages 默认不生效（除非你是付费账号）
启用 GitHub Pages 并确认发布源路径
进入仓库 → Settings → 左侧菜单点 Pages → 在 Build and deployment 区域设置：
-
Source：选
Deploy from a branch -
Branch：选
main（或master，取决于你主分支名） -
Folder：选
/(root)（如果你的index.html就在仓库根目录）；如果放进了docs/目录，就选/docs
保存后，GitHub 会自动构建（通常几秒到一分钟）。页面右上角会出现绿色提示条，显示类似 Live at https://www.php.cn/link/3d22394c88a8a55ffd228fc505045645 —— 这才是你要访问的 URL。
立即学习“前端免费学习笔记（深入）”；
注意：https://github.com/username/repo-name/index.html 是 GitHub 的原始文件预览链接，浏览器会直接下载或显示源码，**不是** GitHub Pages 渲染效果。
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
本地 index.html 里写的相对路径可能在 Pages 上失效
GitHub Pages 发布后，URL 路径结构变了。比如你用项目仓库方式部署，实际访问地址是 https://www.php.cn/link/3d22394c88a8a55ffd228fc505045645，那么所有 CSS、JS、图片的相对引用都会以这个路径为基准。
常见错误现象：页面空白、样式丢失、控制台报 Failed to load resource: the server responded with a status of 404 ()。
- 写
<img src="logo.png">没问题（假设logo.png和index.html同级） - 但写
<script src="js/app.js">时，浏览器会请求https://www.php.cn/link/3d22394c88a8a55ffd228fc505045645js/app.js，不是https://username.github.io/js/app.js - 如果用了
<base href="/"></base>，会导致所有相对路径被强行指向根域名，项目页就全挂了
建议：开发阶段就按子路径（/repo-name/）来组织资源引用，或用 ./ 显式声明当前目录起点，避免隐式依赖根路径。
首次部署后打不开？先检查 URL 和缓存
GitHub Pages 部署成功后，访问的是生成的二级域名或子路径，不是原始仓库地址。容易忽略的点：
- URL 必须带
https://，且大小写敏感（Repo-Name≠repo-name） - 浏览器可能缓存了旧的 404 响应，强制刷新（
Ctrl+Shift+R或Cmd+Shift+R） - 检查 GitHub Pages 设置页是否显示 “Your site is published at …”，没显示说明构建失败（比如
index.html不在所选分支/目录下） - 如果用了自定义域名，要等 DNS 生效（可能长达数小时），先用默认地址验证功能是否正常
最常被跳过的一步：没等 GitHub 页面右上角那个绿色提示出现就急着刷新——它没出现，说明还没部署完，刷新也没用。
