React项目部署GitHub Pages绑定自定义域名后显示空白页求助

我已经将React个人作品集部署到GitHub Pages并正常运行，之后配置了在get.tech购买的自定义域名kevinf.tech，完成了以下配置：

• A记录指向GitHub Pages官方IP：

  1            130642964      kevinf.tech     185.199.108.153     Active
  2            130642965      kevinf.tech     185.199.109.153     Active
  3            130642966      kevinf.tech     185.199.110.153     Active
  4            130642967      kevinf.tech     185.199.111.153     Active
  

• CNAME记录设置：

  www.kevinf.tech     hfang821.github.io      Active
  

• 仓库根目录添加了CNAME文件，GitHub Pages自定义域名字段填入kevinf.tech后显示站点已上线，但访问时仅显示空白页面（favicon正常加载）。仓库地址为hfang821/react_portfolio_v2，开发者工具截图显示相关加载错误。

针对这个问题，可以从以下几个方向排查：

1. 检查React项目的基础路径配置 #

如果是Create React App构建的项目，需要在package.json中更新homepage字段为自定义域名：

"homepage": "https://kevinf.tech"

如果使用Vite构建，需在vite.config.js中设置base参数：

export default defineConfig({
  base: 'https://kevinf.tech/',
  // 其他配置...
})

之前用GitHub Pages默认域名时的路径配置，切换自定义域名后必须同步更新，否则静态资源会从旧路径加载导致404，进而页面空白。

2. 验证资源加载路径 #

打开浏览器开发者工具的「网络」面板，查看JS、CSS等核心资源的请求地址：

• 如果请求地址仍指向hfang821.github.io/xxx而非kevinf.tech/xxx，说明路径配置未生效，需重新构建并部署项目。

3. 确认CNAME文件内容 #

仓库根目录的CNAME文件必须仅包含一行内容：kevinf.tech，不要添加www或其他前缀后缀，确保和GitHub Pages设置的自定义域名完全一致。

4. 等待DNS解析完全生效 #

虽然DNS记录显示「Active」，但全球范围内的DNS缓存可能需要1-2小时才能完全更新。可以通过终端执行nslookup kevinf.tech，检查返回的IP是否为配置的GitHub Pages官方IP。

5. 检查HTTPS强制设置 #

在GitHub Pages的设置页面，确保勾选「Enforce HTTPS」选项。未开启HTTPS可能导致部分浏览器阻止资源加载，引发空白页面问题。开启后可能需要等待几分钟让GitHub生成SSL证书并重新部署站点。

6. 查看控制台错误信息 #

开发者工具的「控制台」面板会显示具体的报错信息：

• 如果是资源404错误，优先排查路径配置；
• 如果是JS执行错误，检查代码中是否有依赖域名的硬编码逻辑；
• 如果是CORS错误，确认资源加载的跨域规则是否符合要求。

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