使用GitHub Pages托管Jekyll站点遭遇404错误求助

Hey there, let’s work through this 404 issue—totally frustrating when your Jekyll site won’t load even after you’ve checked the basics! Since you’ve already confirmed you have an index.md and ruled out obvious index problems, here are targeted checks to fix your .github.io site:

• Check your GitHub Pages build logs first
  GitHub runs a Jekyll build behind the scenes, and even tiny syntax errors can break the deploy (resulting in a 404). Head to your repo’s Actions tab, look for the pages build and deployment workflow. If it’s marked as failed, click into the run to see the error details—common issues include missing front matter in index.md, invalid YAML in _config.yml, or using a Jekyll plugin that GitHub Pages doesn’t support.

• Verify your Pages source settings
  Double-check that GitHub is pulling from the right branch and folder. Go to your repo’s Settings > Pages:

  • Under "Build and deployment", confirm the source is set to Deploy from a branch
  • Make sure the selected branch is the one where your Jekyll files live (most folks use main or master)
  • Ensure the folder is set to /root (unless you intentionally put your site in a /docs subfolder, which is less common for .github.io repos)

• Confirm your index.md has valid Jekyll front matter
  Jekyll requires a front matter block at the top of your index.md to render it as part of the site. Even if it’s empty, it needs to look like this:

  ---
  ---
  

  Without this, GitHub Pages might ignore the file entirely, leading to a 404.

• Wait for deployment and hard-refresh your browser
  First deployments (or large changes) can take 5-10 minutes to go live on GitHub Pages—sometimes longer. Give it a bit of time, then do a hard refresh (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac) to clear your browser’s cached 404 page.

• Double-check filename case and conflicts
  GitHub is case-sensitive for filenames, so make sure your file is exactly index.md (not Index.md or INDEX.md). Also, quick check: is there an index.html file hiding somewhere in your repo that might be causing a conflict?

• Audit your _config.yml for misconfigurations
  A messed-up _config.yml can tank your build. Key things to check:

  • baseurl should be empty for .github.io repos: baseurl: "" (if you set it to something like /site, that’ll break the root URL)
  • Ensure permalink settings are valid
  • Remove any plugins that aren’t on GitHub’s supported plugins list—custom plugins will cause the build to fail.

If none of these fix it, try building the site locally first. Install Jekyll on your machine, run bundle exec jekyll serve in your repo folder, and see if the site loads correctly. If it works locally but not on GitHub Pages, the problem is definitely tied to GitHub’s build environment or settings.

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