如何在使用GitHub Actions的Jekyll GitHub Pages中配置自定义404页面

问题根源 #

你遇到的页面叠加问题，主要是两个原因：

• 用layout: default时，默认布局的内容和你自定义的完整HTML结构重复渲染，导致内容叠加；
• 静态资源用了相对路径，404页面在子路径下加载时找不到资源，样式失效看起来像叠加。

正确配置方案 #

方案1：直接用纯静态404.html（推荐） #

你的404.html已经是完整的HTML页面，不需要Jekyll布局处理，只需调整路径并确保GitHub Pages能识别：

1. 删掉所有尝试过的404.md文件，保留根目录的404.html。
2. 修正静态资源路径：因为站点部署在/SMD-Desktop/website子路径，所有相对路径要改成绝对路径，比如：
   • 把./index.html改成/SMD-Desktop/website/index.html
   • 把styles/style.css改成/SMD-Desktop/website/styles/style.css
   • 图片、JS、favicon的路径同理，全部以/SMD-Desktop/website/开头。
3. 检查GitHub Actions工作流：如果你的Jekyll站点根目录是website文件夹，要把build步骤的source参数改成./website，确保构建路径正确：

   - name: Build with Jekyll
     uses: actions/jekyll-build-pages@v1
     with:
       source: ./website
       destination: ./_site
   

方案2：用Jekyll布局生成404页面（适合复用站点导航） #

如果想复用站点的导航栏等布局，避免重复代码：

1. 删除根目录的完整404.html，创建_includes/404-content.html，只保留404的主体内容：

   <main class="content">
     <i class="fa fa-exclamation-circle icon-big"></i>
     <h1 class="heading text-center">Download Unavailable</h1>
     <h3 class="subheading text-center">
       Application is still in development and downloads are not available at the moment
     </h3>
     <a href="https://github.com/noahweasley/SMD-Desktop" class="navigate text-center"> View GitHub Repo </a>
   </main>
   

2. 创建根目录的404.md，用默认布局引入内容：

   ---
   layout: default
   permalink: /404.html
   title: Unavailable | S.M.D - Spotify Music Downloader
   ---
   {% include 404-content.html %}
   

3. 确保布局中的资源路径正确：默认布局里的CSS、JS路径也要改成绝对路径，避免子路径下加载失败。

验证 #

部署后访问一个不存在的路径（比如https://noahweasley.github.io/SMD-Desktop/website/xxx），检查：

• 页面内容正常，没有叠加；
• 浏览器控制台没有资源加载失败的404错误。

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