Jekyll+GitHub Pages本地serve报错404：文件未找到求助

嘿，别慌！这种本地环境和GitHub Pages远程环境不一致的问题我碰过好多次，咱们一步步排查解决：

• 先对齐Jekyll版本（最常见的原因）
  GitHub Pages用的是特定版本的Jekyll和依赖包，如果你本地全局安装的Jekyll版本和它不一样，就容易出现路径解析的差异。解决方法：

  1. 在你的站点根目录创建一个Gemfile（如果还没有的话），内容如下：

     source "https://rubygems.org"
     gem "github-pages", group: :jekyll_plugins
     

  2. 运行bundle install安装匹配的依赖
  3. 之后用bundle exec jekyll serve启动本地服务器，而不是直接用jekyll serve。这个命令会强制使用GitHub Pages指定的Jekyll版本，和远程环境保持一致。

• 检查_config.yml里的路径配置
  打开你的_config.yml，确认baseurl和url设置是否正确：

  • 如果你的GitHub Pages站点是https://yourusername.github.io（根域名站点），那baseurl应该设为""（空字符串），url设为"https://yourusername.github.io"
  • 如果是项目站点（比如https://yourusername.github.io/your-blog），那baseurl必须是"/your-blog"，url是"https://yourusername.github.io"
    启动本地服务器后，要访问对应的路径：比如baseurl是/blog的话，得去http://localhost:4000/blog/，而不是直接访问根路径http://localhost:4000/，不然就会出现404。

• 清理本地缓存文件
  有时候Jekyll的缓存会残留旧的配置或文件，即使你撤销了修改也会影响。手动删除这两个文件夹：

  • _site：Jekyll生成的静态文件目录
  • .jekyll-cache：本地缓存目录
    然后重新用bundle exec jekyll serve启动服务器，让Jekyll重新生成所有文件。

• 检查模板中的资源引用路径
  虽然你说没修改front matter，但可以快速确认一下博客模板里的CSS等资源是不是用了正确的变量引用。比如CSS的引用应该是{{ site.baseurl }}/assets/main.css，而不是硬编码的/blog/assets/main.css——后者在本地如果baseurl没设置对的话就会找不到。不过既然远程正常，这个可能不是主要问题，但排查一下也没坏处。

如果按上面的步骤操作后还是有问题，可以试试在启动服务器时加上--trace参数，比如bundle exec jekyll serve --trace，这样能看到更详细的错误日志，方便进一步定位问题。

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