如何在GitHub Pages静态网站中引入自定义CSS？-css教程-PHP中文网

绝对路径 /css/style.css 在项目站点（username.github.io/repo）下加载失败，因为浏览器将 / 解析为网站根路径 https://username.github.io/，而实际资源位于 https://username.github.io/repo/css/style.css，导致 404。

如何在github pages静态网站中引入自定义css？

绝对路径 /css/style.css 在项目站点（username.github.io/repo）下必然 404，必须改用相对路径或显式声明。

为什么 `/css/style.css` 在项目站点里加载失败

GitHub Pages 用户站点（username.github.io）根路径是 /，所以 /css/style.css 解析为 https://username.github.io/css/style.css，能命中；但项目站点（username.github.io/repo）实际根路径是 /repo/，此时浏览器仍按字面解析 /css/style.css → https://username.github.io/css/style.css，而真实资源在 https://username.github.io/repo/css/style.css，结果就是 404。

浏览器不会“猜”你当前在哪个子目录下——它严格按 URL 开头的 / 判定为网站根路径。

用户站点：发布源为 main 分支根目录 → 网站根路径 = /
项目站点：发布源为 main 分支的 docs 目录或 gh-pages 分支 → 网站根路径 = /repo/
所有以 / 开头的资源路径（href="/css/style.css"、src="/js/app.js"）都按网站根路径解析，不随 HTML 文件位置变化

手动写 HTML 时：用相对路径或

是最轻量的修复方式，适合纯静态展示页。

GitHub Push 自动推送

使用自动 SSH 和远程配置实现安全的 GitHub 推送自动化。适用于执行 `git push`、自动化推送或处理冲突等场景。

下载

在 index.html 的中添加：（把 repo 换成你仓库名）
之后所有相对路径（如 css/style.css、./img/logo.png）都会自动补上前缀，变成 https://username.github.io/repo/css/style.css
必须放在内，且在任何、<script></script> 之前
不能写成 —— . 不会被 GitHub Pages 解析为当前子路径，它还是按服务器根处理
用了自定义域名（如 yoursite.com），值仍应填 /repo/，不是 https://yoursite.com/repo/ —— 协议和域名由浏览器自动补全

Vite / Vue / React 构建项目：必须配 `base` 参数

构建工具生成的 HTML 依赖 base 控制资源前缀。若不设，打包出的 index.html 里所有 assets/ 引用仍是 /assets/xxx.js，必然 404。

Vite 项目：在 vite.config.ts 中设 base: "/repo/"（不是 /）
Vue CLI 项目：修改 vue.config.js 的 publicPath: "/repo/"
Next.js（next export 场景）：设置 assetPrefix: "/repo/"

容易被忽略的关键点

会影响整个页面所有相对 URL：链接、图片、表单 action 都会受其影响。如果你页面里有跳转逻辑（比如导航栏链接写成 about.html），确保它们也用相对路径写，否则可能跳到 https://username.github.io/repo/about.html 而不是你预期的同级位置。另外，CNAME 文件存在时，依然要按 GitHub Pages 的路径（/repo/）写，而不是你的自定义域名路径——GitHub Pages 的路由解析完全独立于 DNS 和 CNAME。