使用GitHub Actions Next.js工作流部署Nextra站点时遇Jekyll错误

我用Nextra搭建静态网站，通过GitHub Actions的Next.js工作流部署时，碰到Jekyll找不到CSS文件的错误，初始错误信息：

Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
No such file or directory @ dir_chdir - /github/workspace/docs

按照要求在仓库工作流中添加nextjs.yaml后，重新运行任务仍报错，完整错误日志如下：

build
 Logging at level: debug GitHub Pages: github-pages v228 GitHub Pages: jekyll v3.9.3 
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/./docs Destination: /github/workspace/./docs/_site 
Incremental build: disabled. Enable with --incremental 
Generating... 
Generating: JekyllOptionalFrontMatter::Generator finished in 8.747e-06 seconds. 
Generating: JekyllReadmeIndex::Generator finished in 4.569e-06 seconds. 
Generating: Jekyll::Paginate::Pagination finished in 2.365e-06 seconds. 
Generating: JekyllRelativeLinks::Generator finished in 2.0878e-05 seconds. 
Generating: JekyllDefaultLayout::Generator finished in 9.658e-06 seconds. 
Generating: JekyllTitlesFromHeadings::Generator finished in 5.65e-06 seconds. 
Rendering: assets/css/style.scss 
Pre-Render Hooks: assets/css/style.scss 
Rendering Markup: assets/css/style.scss github-pages 228 | 
Error: No such file or directory @ dir_chdir - /github/workspace/docs 

问题根源 #

GitHub Pages默认会自动启用Jekyll构建流程，但Nextra是基于Next.js的静态站点生成器，完全不需要Jekyll参与处理。Jekyll试图读取指定目录下的SCSS文件，但该目录结构不符合Jekyll的预期，且Nextra的构建产物也不需要Jekyll二次处理，因此触发错误。

解决方案 #

1. 添加.nojekyll文件
   在仓库根目录创建一个空的.nojekyll文件，告诉GitHub Pages跳过Jekyll构建步骤。

2. 检查并修正Next.js工作流配置
   确保nextjs.yaml工作流中指定了正确的构建产物目录（Nextra默认构建输出到out目录），并正确配置部署步骤。示例配置如下：

name: Deploy Next.js site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"
      - name: Install dependencies
        run: npm install
      - name: Build static site
        run: npm run build
      - name: Upload build artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3. 验证部署源设置
   在GitHub仓库的「Settings」→「Pages」页面，确认部署源选择的是「GitHub Actions」，而非「Deploy from a branch」（后者会触发Jekyll构建）。

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