GitHub Pages部署后网站无法正常访问，提示404错误如何解决？

Question

在使用GitHub Pages部署网站时，如果遇到404错误，通常可能是以下原因导致：1. 仓库名称不符合要求（如用户页面必须命名为`username.github.io`）；2. 部署分支设置错误（需确保选择正确的分支，如`main`或`gh-pages`）；3. 路径配置问题（项目页面需要将代码放在`docs`文件夹或根目录下）；4. 自定义域名配置不当。解决方法：检查仓库名称和分支设置是否正确，确认 `_config.yml` 文件中的 `baseurl` 和 `url` 配置无误，同时验证 CNAME 文件内容与自定义域名是否匹配。若问题依旧存在，可尝试清除浏览器缓存或通过 GitHub Actions 日志排查具体错误原因。

Answer 1

1. 基础概念与常见问题

在使用 GitHub Pages 部署网站时，404 错误是一个常见的问题。以下是可能导致该错误的原因：

• 仓库名称不符合要求（如用户页面必须命名为 `username.github.io`）。
• 部署分支设置错误（需确保选择正确的分支，如 `main` 或 `gh-pages`）。
• 路径配置问题（项目页面需要将代码放在 `docs` 文件夹或根目录下）。
• 自定义域名配置不当。

解决这些问题的第一步是了解每个部分的功能和配置要求。

2. 仓库名称与分支设置检查

仓库名称对于 GitHub Pages 的正确运行至关重要。以下是一些关键点：

1. 用户页面的仓库名称必须为 `username.github.io`。
2. 项目页面的仓库名称可以自定义，但需要确保部署分支和路径正确。

此外，部署分支的选择也非常重要。通常，默认分支为 `main` 或 `gh-pages`。可以通过以下步骤检查分支设置：

# 进入仓库设置页面
Settings -> GitHub Pages -> Source

# 确保选择了正确的分支
例如：main / gh-pages
    

如果分支设置错误，GitHub 将无法找到正确的文件并返回 404 错误。

3. 路径配置与文件结构分析

路径配置问题通常发生在项目页面中。以下是具体的配置要求：

场景	要求
项目页面	代码需要放在 `docs` 文件夹或根目录下。
用户页面	代码直接放在根目录即可。

以 Jekyll 为例，`_config.yml` 文件中的 `baseurl` 和 `url` 配置需要特别注意：

url: "https://username.github.io"
baseurl: "/project-name"
    

如果这些值配置错误，GitHub Pages 可能无法正确解析路径，从而导致 404 错误。

4. 自定义域名配置排查

自定义域名配置不当也是导致 404 错误的常见原因。以下是排查步骤：

首先，确保 CNAME 文件内容与自定义域名匹配。例如：

mycustomdomain.com
    

其次，检查 DNS 设置是否正确。通常需要添加一条 CNAME 记录指向 `username.github.io`。

最后，可以通过以下流程图理解整个配置过程：

graph TD;
            A[开始] --> B{是否配置自定义域名};
            B --是--> C[检查 CNAME 文件];
            B --否--> D[检查仓库名称和分支];
            C --> E{CNAME 文件是否正确};
            E --否--> F[修正 CNAME 文件];
            E --是--> G[检查 DNS 设置];
            G --> H{DNS 是否正确};
            H --否--> I[修正 DNS 设置];
            H --是--> J[完成];

5. 高级排查与日志分析

如果上述方法均未解决问题，可以尝试以下高级排查手段：

• 清除浏览器缓存。
• 查看 GitHub Actions 日志，定位具体错误原因。

GitHub Actions 日志提供了详细的构建信息。通过以下步骤访问日志：

# 进入仓库 Actions 页面
Actions -> 查看最新工作流日志

# 搜索关键字如 "Error" 或 "Failed"
    

日志中可能包含路径、分支或配置相关的错误提示，帮助进一步定位问题。