GitHub Pages部署需严格匹配仓库名或分支结构：用户主页须为username.github.io且文件在main/master根目录；项目页可任意命名但需在Settings中指定源分支/文件夹；资源路径须用相对路径或base标签；不支持服务端逻辑；SPA刷新404问题可通过同内容404.html解决。
GitHub Pages 要求仓库名或分支名必须匹配
GitHub Pages 不是随便 push 就能上线的，它严格依赖仓库命名或分支结构。如果你用的是用户/组织主页（比如 username.github.io），仓库名必须是 username.github.io，且内容得在 main 或 master 分支根目录下——不能套在 /src 或 /dist 里。
常见错误现象：404 Not Found 页面，但 GitHub 上明明有 index.html；或者页面空白，控制台报 Failed to load resource: the server responded with a status of 404 ()，大概率是路径没对上。
- 个人主页：仓库名必须为
username.github.io，文件放在main分支根目录 - 项目页（Project Pages）：任意仓库名，但需在 Settings → Pages → Source 里手动选分支 + 文件夹（如
gh-pages分支，或main分支下的/docs文件夹） - 不支持子目录部署为独立域名，比如
username.github.io/myapp只能通过项目页实现，且路由要配相对路径
HTML 中的资源路径别写死成绝对路径
本地双击打开 index.html 能看到图片和 CSS，一推到 GitHub Pages 就全挂了？八成是用了 /css/style.css 这种以 / 开头的绝对路径。GitHub Pages 的项目页地址是 https://username.github.io/repo-name/，浏览器会把 /css/... 解析成 https://username.github.io/css/...，而不是你仓库里的位置。
正确做法是统一用相对路径，或用 <base href="./"> 控制基准 URL（注意结尾斜杠）。
立即学习“前端免费学习笔记（深入）”；
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 图片、CSS、JS 全部用
./css/style.css、../images/logo.png这类写法 - 如果用了
<base href="/repo-name/">，那所有相对路径都会拼上去，适合项目页，但每次改仓库名都要同步改href - Vite / React 等构建工具默认输出带
/前缀的资源路径，部署前务必配置base: "./"（Vite）或homepage: "."（Create React App）
GitHub Pages 默认不运行服务端逻辑，纯静态才稳
GitHub Pages 就是个 HTTP 文件服务器，不执行 PHP、Node.js、Python，也不支持 .htaccess 重写规则。你放个 api.php 或 server.js，它只会被当文本下载，不会运行。
想做表单提交、用户登录、数据库交互？要么换平台（Vercel、Netlify），要么前端调第三方 API（比如 Formspree、Airtable、Supabase）。
- 所有 JS 里的
fetch("/api/submit")必须指向外部服务，否则会 404 - 本地测试时用
python3 -m http.server或 VS Code Live Server，别依赖双击打开，因为 file:// 协议下 fetch 会被 CORS 拦截 - 如果用了路由库（如 Vue Router、React Router），启用
history模式后，刷新 404 是正常的——GitHub Pages 不会自动 fallback 到index.html，得靠404.html曲线救国（见下条）
单页应用（SPA）刷新 404？加个 404.html 就行
Vue、React 项目用 history 路由，访问 https://user.github.io/app/about 没问题，但直接刷新，GitHub Pages 找不到 /about 这个路径，返回默认 404 页面。这不是 bug，是设计如此。
解决方法很简单：在项目根目录放一个 404.html，内容和 index.html 完全一样。GitHub Pages 在找不到路径时，会优先返回这个文件，JS 路由就能接管并渲染正确页面。
-
404.html必须和index.html同级，且名字必须是小写的404.html（GitHub 大小写敏感） - 不需要任何额外配置，也不用改 Webpack/Vite 的 output.publicPath
- 别试图用
redirects或_redirects文件——GitHub Pages 不支持 Netlify 那套
最常被忽略的一点：改完设置后，GitHub Pages 构建可能有缓存，尤其是 DNS 或 CDN 层。等 1–2 分钟再刷，别急着重推。还有，检查 GitHub 仓库 Settings → Pages 页面右上角有没有黄色警告图标——那里会明确告诉你哪一步卡住了。
