Jekyll主题在GitHub Pages中CSS无法渲染问题求助

1. 替换CSS引用路径为动态拼接 #

别用硬写的绝对路径（比如<link href="/css/style.css">），改用Jekyll的变量适配不同环境：

<link rel="stylesheet" href="{{ site.baseurl }}/css/main.css">

这样本地和GitHub Pages都会自动匹配正确路径。

2. 正确配置baseurl #

打开_config.yml，根据你的站点类型添加配置：

• 若为项目站点（比如username.github.io/your-repo）：

baseurl: "/your-repo-name"

注意开头必须带斜杠，结尾不要加斜杠。

• 若为用户/组织站点（直接username.github.io）：

baseurl: ""

修改后本地重启Jekyll服务（bundle exec jekyll serve），确认本地加载正常后再推送到GitHub。

3. 检查CSS文件的编译与位置 #

• 如果你用Sass编写样式，主SCSS文件（比如assets/css/main.scss）开头必须添加两行---（YAML front matter），否则Jekyll不会将其编译为CSS：

---
---
@import "base";
@import "layout";
// 其他Sass文件导入语句

• 确认编译后的CSS文件已存在于GitHub仓库的对应目录（比如css/main.css），且未被.gitignore规则忽略。

4. 查看GitHub Pages构建日志 #

进入仓库的「Settings」→「Pages」，找到「Build and deployment」下的构建记录，点击查看是否有报错信息（比如CSS编译失败、文件找不到等），这些日志能直接定位问题根源。

内容的提问来源于stack exchange，提问作者Bader Bouarki