基于Bootstrap的静态网站在Jekyll构建并发布到GitHub Pages时失败

问题背景 #

用Bootstrap 5开发的网站，通过Jekyll构建发布到GitHub Pages时失败，仓库无docs目录，但构建过程尝试访问/github/workspace/docs路径，已尝试更换Bootstrap导入方式、修改页面源路径，均未解决问题。

核心错误 #

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

完整错误日志 #

Run actions/jekyll-build-pages@v1
/usr/bin/docker run --name ghcrioactionsjekyllbuildpagesv108_75fe66 --label ef7d85 --workdir /github/workspace --rm -e "INPUT_SOURCE" -e "INPUT_DESTINATION" -e "INPUT_FUTURE" -e "INPUT_BUILD_REVISION" -e "INPUT_VERBOSE" -e "INPUT_TOKEN" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHUB_WORKFLOW_SHA" -e "GITHUB_WORKSPACE" -e "GITHUB_ACTION" -e "GITHUB_EVENT_PATH" -e "GITHUB_ACTION_REPOSITORY" -e "GITHUB_ACTION_REF" -e "GITHUB_PATH" -e "GITHUB_ENV" -e "GITHUB_STEP_SUMMARY" -e "GITHUB_STATE" -e "GITHUB_OUTPUT" -e "RUNNER_OS" -e "RUNNER_ARCH" -e "RUNNER_NAME" -e "RUNNER_ENVIRONMENT" -e "RUNNER_TOOL_CACHE" -e "RUNNER_TEMP" -e "RUNNER_WORKSPACE" -e "ACTIONS_RUNTIME_URL" -e "ACTIONS_RUNTIME_TOKEN" -e "ACTIONS_CACHE_URL" -e "ACTIONS_ID_TOKEN_REQUEST_URL" -e "ACTIONS_ID_TOKEN_REQUEST_TOKEN" -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/Coding-Portfolio-Website/Coding-Portfolio-Website":"/github/workspace" ghcr.io/actions/jekyll-build-pages:v1.0.8
Configuration file: none
  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
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
 ** Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':
                    No such file or directory @ dir_chdir - /github/workspace/docs**
         Requiring: jekyll-seo-tag
/usr/local/bundle/gems/jekyll-sass-converter-1.5.2/lib/jekyll/converters/scss.rb:86:in `chdir': No such file or directory @ dir_chdir - /github/workspace/docs (Errno::ENOENT)
         Requiring: jekyll-coffeescript
         Requiring: jekyll-commonmark-ghpages
    from /usr/local/bundle/gems/jekyll-sass-converter-1.5.2/lib/jekyll/converters/scss.rb:86:in `sass_load_paths'
         Requiring: jekyll-gist
         Requiring: jekyll-github-metadata
    from /usr/local/bundle/gems/jekyll-sass-converter-1.5.2/lib/jekyll/converters/scss.rb:114:in `sass_configs'
         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 1.15e-05 seconds.
        Generating: JekyllReadmeIndex::Generator finished in 7.201e-06 seconds.
        Generating: Jekyll::Paginate::Pagination finished in 3.901e-06 seconds.
        Generating: JekyllRelativeLinks::Generator finished in 2.9902e-05 seconds.
        Generating: JekyllDefaultLayout::Generator finished in 1.1501e-05 seconds.
        Generating: JekyllTitlesFromHeadings::Generator finished in 7.5e-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
    from /usr/local/bundle/gems/jekyll-sass-converter-1.5.2/lib/jekyll/converters/scss.rb:119:in `convert'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:101:in `block in convert'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:99:in `each'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:99:in `reduce'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:99:in `convert'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:83:in `render_document'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/renderer.rb:62:in `run'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:479:in `render_regenerated'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:472:in `block in render_pages'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:471:in `each'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:471:in `render_pages'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:192:in `render'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/site.rb:71:in `process'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/command.rb:28:in `process_site'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/commands/build.rb:65:in `build'
    from /usr/local/bundle/gems/jekyll-3.9.3/lib/jekyll/commands/build.rb:36:in `process'
    from /usr/local/bundle/gems/github-pages-228/bin/github-pages:70:in `block (3 levels) in <top (required)>'
    from /usr/local/bundle/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `block in execute'
    from /usr/local/bundle/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `each'
    from /usr/local/bundle/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `execute'
    from /usr/local/bundle/gems/mercenary-0.3.6/lib/mercenary/program.rb:42:in `go'
    from /usr/local/bundle/gems/mercenary-0.3.6/lib/mercenary.rb:19:in `program'
    from /usr/local/bundle/gems/github-pages-228/bin/github-pages:6:in `<top (required)>'
    from /usr/local/bundle/bin/github-pages:23:in `load'
    from /usr/local/bundle/bin/github-pages:23:in `<main>'

原因分析 #

1. 日志显示Jekyll构建时的Source路径被设为/github/workspace/./docs，但仓库不存在该目录，导致Scss转换器切换目录失败。
2. 无Jekyll配置文件（Configuration file: none），Jekyll默认遵循GitHub Pages规则，误将docs作为源目录。

修复方案 #

方案1：添加Jekyll配置文件指定源目录 #

在仓库根目录创建_config.yml，明确指定源目录为根目录：

source: "."
destination: "_site"

方案2：调整GitHub Pages构建设置 #

1. 进入仓库Settings页面，找到Pages选项卡。
2. 在Build and deployment区域，将Source设为Deploy from a branch，选择目标分支（如main），并将Folder设置为/(root)，而非/docs。

方案3：迁移文件到docs目录（可选） #

若希望保留docs作为源目录，将所有网站文件（assets、HTML文件等）移动到仓库根目录下的docs文件夹中。

验证步骤 #

1. 提交修改后的配置或文件结构到仓库。
2. 重新触发GitHub Pages构建，查看日志是否正常。
3. 访问网站确认页面加载正常。

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