Jekyll部署至GitHub Pages遇404错误求助

Hey there, let’s work through that 404 issue on your portfolio site step by step—here are the most common fixes to check first:

1. Verify GitHub Pages Deployment Settings #

• Head to your repo’s Settings > Pages section. Double-check that the source is set to the gh-pages branch and the directory is /(root) (unless you configured Jekyll to build into a docs folder, which is less common for portfolio sites).
• Look for the latest deployment status on that same page. If there’s a failed build, click into the details to view the log—GitHub will often flag Jekyll-specific errors (like missing gems, invalid YAML in _config.yml, or broken front matter) that prevent your site from generating correctly.

2. Fix Your _config.yml BaseURL & URL #

This is the #1 culprit for subpath site 404s (since your site lives at /portfolio instead of the root domain):

• Open your _config.yml and make sure these lines are set correctly:

  baseurl: "/portfolio"
  url: "https://linus345.github.io"
  

• Never omit the baseurl when your site is hosted in a repo subpath—Jekyll uses this to generate correct internal links.

3. Audit Internal Links & Permalinks #

• All internal links (navigation, images, CSS, page references) should use the site.baseurl variable to ensure they point to the right subpath. For example:
  • Instead of <a href="/about">About</a>, use <a href="{{ site.baseurl }}/about">About</a>
  • For images: <img src="{{ site.baseurl }}/assets/img/photo.jpg" alt="My photo">
• Check your permalink settings in _config.yml. If you’re using a custom format (like permalink: /:title/), ensure it doesn’t include absolute paths (e.g., https://linus345.github.io/about is bad—stick to relative paths like /about/).

4. Compare Local Build to GitHub’s gh-pages Branch #

• Run bundle exec jekyll build locally to generate the _site folder. Inspect its structure: do you see an index.html at the root? Are other pages (like about.html or projects/index.html) present?
• Compare the contents of your local _site folder to what’s in your gh-pages branch on GitHub. If files are missing or paths differ, it means either:
  • Your local build has errors you didn’t notice (check the terminal output when running jekyll build), or
  • You’re manually uploading source files instead of the built static content (if you’re not using GitHub’s automatic Jekyll build).

5. Wait for GitHub Pages Propagation #

Sometimes, even after a successful build, it can take 5-10 minutes for GitHub Pages to fully propagate changes. If you just pushed updates, give it a few minutes before reloading the site.

If none of these fix the issue, share a snippet of your _config.yml and an example of a broken link from your site—we can dig deeper!

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