.nojekyll 文件详解

.nojekyll 是一个特殊的文件名，用在 GitHub Pages 等静态网站托管服务中，作用是禁用 Jekyll（GitHub Pages 默认的静态网站生成器）的处理。它是一个空文件，没有文件内容，但它的存在会对部署行为产生重要影响。

---

.nojekyll 的作用

1. 禁用 Jekyll

   • Jekyll 是 GitHub Pages 默认使用的静态网站生成器。它会忽略文件和文件夹名以 _（下划线）开头的内容（例如 _config.yml 或 _data），因为 Jekyll将这些视为特定用途的配置文件或数据文件。
   • 如果你的静态网站不使用 Jekyll（例如，直接托管 HTML 文件或用其他工具生成的网站），.nojekyll 文件可以禁用这种行为，从而避免误删文件。

2. 保持文件原样托管

   • 有时你希望所有文件，包括以 _ 开头的文件夹或文件，都被完整上传和展示。在这种情况下，.nojekyll 文件非常有用。

---

常见应用场景

1. 非 Jekyll 的静态站点

• 如果你使用其他工具（例如 Hugo、VuePress、Next.js 或自己手写的 HTML 文件）生成的静态网站，不需要 Jekyll 的处理逻辑，那么你可以添加 .nojekyll 文件。

2. 文档或非网站用途的项目

• 如果你在 GitHub Pages 上部署文档、API 输出文件、或其他非网站内容（例如 PDF 或 JSON 数据），而这些内容包含以 _ 开头的文件或文件夹时，需要 .nojekyll 来确保它们正常展示。

3. 前端工程

• 在前端工程中，特别是使用 Webpack、Vite 等工具生成的静态文件时，这些工具的输出可能包含以 _ 开头的文件夹，例如 _assets。这时 .nojekyll 是必要的。

4. 教学或代码演示项目

• 用于展示静态文件结构，比如文件夹名可能以 _ 开头的示例代码文件或实验文件夹。

---

如何创建 .nojekyll

1. 在本地创建一个文件名为 .nojekyll 的空文件。
2. 将文件上传到你的 gh-pages 分支或任何部署的根目录。
3. 提交到远程仓库后，GitHub Pages 服务将自动识别并禁用 Jekyll。

---

示例场景

项目结构（未添加 .nojekyll）：

gh-pages/
├── index.html
├── _assets/
│   ├── style.css
│   └── script.js

如果没有 .nojekyll，GitHub Pages 可能会忽略 _assets 文件夹。

添加 .nojekyll 后：

gh-pages/
├── .nojekyll
├── index.html
├── _assets/
│   ├── style.css
│   └── script.js

此时，_assets 文件夹中的内容会被正常部署。

---

总结

• .nojekyll 用于禁用 GitHub Pages 默认的 Jekyll 处理。
• 常用于非 Jekyll 静态站点、复杂的前端项目输出或非网站用途的文件部署。
• 添加 .nojekyll 文件的项目类型包括：前端工程、非 Jekyll 网站、静态文档站点等。