为什么使用.nojekyll

github 工作流

发布日期: 2025-01-25

更新日期: 2025-03-13

文章字数: 862

阅读时长: 3 分

背景

在构建Astro主题播客到GitHub pages时，遇到页面不不能渲染的问题，导致构建成静态页面也无法渲染，并且GitHub pages只支持静态页面渲染，并不支持服务端渲染。

为什么.nojekyll

在 GitHub Pages 上，.nojekyll 文件的存在是很重要的，它可以确保某些文件和目录（如以下划线开头的文件和 CSS 预处理生成的文件）不会被 Jekyll 处理和忽略。

原因分析

GitHub Pages 默认使用 Jekyll：GitHub Pages 默认启用 Jekyll，一个静态网站生成器。当这个功能启用时，GitHub 会尝试处理你的页面，包括生成一些默认的规则，比如跳过以 . 开头的文件和以 _ 开头的文件（例如 _layouts、_includes 等）。因此，如果你有文件名或路径以 _ 开头，它们可能会被自动忽略。
防止与 Jekyll 的冲突：创建一个 .nojekyll 文件告诉 GitHub Pages 忽略 Jekyll 对项目的处理。这样，GitHub 就不会尝试处理你的文件，确保你的资源（如 CSS 文件）能够按预期正常加载。
确保所有文件都能正常访问：有了 .nojekyll，所有静态资源将会被正常访问，即使它们是以 _ 开头的，这样就能确保样式和其他静态文件能够被正确加载和应用。

在 GitHub Actions 中添加 `.nojekyll`

在你的 GitHub Actions 工作流程中，你可以通过在构建之后简单创建一个 .nojekyll 文件来确保这个文件存在。例如你可以这样来更新构建步骤：

- name: 构建文档  
  env:  
    NODE_OPTIONS: --max_old_space_size=8192  
  run: |-  
    npm run build  
    # 创建 .nojekyll 文件  
    touch dist/.nojekyll

使用 .nojekyll 文件是确保你的静态站点在 GitHub Pages 上正常工作的一个好方法，尤其是当你依赖自定义文件结构或以 _ 开头的文件时。在将来的任何静态站点部署中，记得在构建后的输出目录中创建 .nojekyll 文件，以避免潜在的问题！

贴上我的配置：

name: Deploy site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: 
      - dev

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
      # 拉取 github 仓库代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # submodules: true

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
         # 选择要使用的 node 版本
          # node-version: ${{ matrix.node-version }}
          node-version: 22.13.1
          # 设置发包 npm 地址仓库
          registry-url: https://registry.npmjs.org
          # 缓存 npm 依赖
          cache: npm
      - name: Install dependencies 📦️
        run: npm install
        
      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          npm run build
          > dist/.nojekyll

      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          token: ${{ secrets.PATH_TOKEN }}
          repository-name: xxxx/xxxx.github.io
          branch: devpages
          folder: dist

附件

提示：

Logging at level: debug GitHub Pages: github-pages v232 GitHub Pages: jekyll v3.10.0 Theme: jekyll-theme-primer Theme source: /usr/local/bundle/gems/jekyll-theme-primer-0.6.0 Requiring: jekyll-github-metadata Requiring: jekyll-seo-tag Requiring: jekyll-coffeescript Requiring: jekyll-commonmark-ghpages Requiring: jekyll-gist Requiring: jekyll-github-metadata Requiring: jekyll-paginate Requiring: jekyll-relative-links Requiring: jekyll-optional-front-matter Requiring: jekyll-readme-index Requiring: jekyll-default-layout Requiring: jekyll-titles-from-headings GitHub Metadata: Initializing... Source: /github/workspace/. Destination: /github/workspace/./_site Incremental build: disabled. Enable with --incremental Generating