GitHub Pages: 根目录 vs /docs 文件夹

了解两种部署方式的区别，选择最适合您项目的方法

两种部署来源对比

📂 根目录 (/)

  • ✅ 默认选项 - 大多数项目的首选
  • 🚀 简单直接 - 文件直接放在仓库根目录
  • 🔄 自动构建 - 支持Jekyll等静态站点生成器
  • 📝 代码文档一体化 - 代码和网站在同一位置
  • ⚠️ 可能杂乱 - 项目文件与网站文件混合
典型文件结构：
repository/
├── index.html         # 网站主页
├── css/
│   └── style.css   # 样式文件
├── js/
│   └── script.js   # 脚本文件
├── README.md     # 项目说明
└── src/               # 源代码目录

📁 /docs 文件夹

  • 📋 分离关注点 - 网站文件与项目代码分离
  • 🧹 整洁有序 - 项目结构更清晰
  • 🔧 保留构建输出 - 适合静态站点生成器的输出目录
  • 📚 适合项目文档 - 专门用于文档网站
  • 🔄 需要额外配置 - 需在设置中指定/docs文件夹
典型文件结构：
repository/
├── docs/             # 网站文件目录
│   ├── index.html   # 网站主页
│   ├── css/
│   └── js/
├── README.md     # 项目说明
├── src/               # 源代码目录
└── package.json   # 项目配置

GitHub Pages 设置位置：

仓库 Settings → Pages → Build and deployment → Source

选择 "Deploy from a branch" 然后选择：

  • / (root) - 从根目录部署
  • /docs - 从/docs文件夹部署

何时使用哪种方式？

使用根目录的情况

  • 纯静态网站项目 - 仓库专门用于网站
  • 用户/组织站点 - username.github.io
  • 简单项目演示 - 代码和演示紧密结合
  • Jekyll博客 - 利用GitHub Pages内置支持

使用/docs文件夹的情况

  • 代码库的文档网站 - 如API文档
  • 静态站点生成器输出 - 如VuePress、Docusaurus
  • 项目演示与代码分离 - 保持代码库整洁
  • 大型项目 - 需要清晰的文件组织

针对您的具体情况

对于您的 html_css.github.io 仓库：

建议使用根目录部署，因为这是一个专门用于网站的仓库，不需要将网站文件与代码分离。

操作指南

从根目录部署的步骤

  1. 将网站文件直接放在仓库根目录
  2. 确保有 index.html 文件
  3. 进入仓库 Settings → Pages
  4. 在 Source 部分选择 "Deploy from a branch"
  5. 选择分支（通常是 main）和 /(root) 文件夹
  6. 点击 Save

从/docs文件夹部署的步骤

  1. 在仓库中创建 docs 文件夹
  2. 将所有网站文件放入 docs 文件夹
  3. 确保 docs 文件夹中有 index.html 文件
  4. 进入仓库 Settings → Pages
  5. 在 Source 部分选择 "Deploy from a branch"
  6. 选择分支（通常是 main）和 /docs 文件夹
  7. 点击 Save

转换现有设置

如果您想从一种方式转换到另一种：

  1. 在本地移动文件（从根目录到/docs或反之）
  2. 提交更改到GitHub
  3. 更新GitHub Pages设置中的Source选项
  4. 等待重新部署完成
查看根目录结构示例 查看/docs结构示例