基于Node的GitHub Pages部署异常：修改内容无法更新求助

可能的原因 #

• 本地build产物未同步到GitHub仓库：执行npm run build后，没有将生成的build文件夹改动提交并推送到远程仓库，GitHub Pages只会拉取仓库指定分支的内容。
• GitHub Pages缓存机制：平台会对静态资源做CDN或浏览器缓存，即使代码更新，缓存未过期时仍会加载旧内容。
• 部署分支配置错误：GitHub Pages设置的部署分支与你推送新代码的分支不匹配，比如配置了gh-pages分支但你只推了main分支的改动。
• React项目路径配置缺失：部署到GitHub Pages子仓库（非username.github.io根域名）时，未在package.json中配置homepage字段，导致build后资源路径错误，表现为加载旧缓存页面。
• gh-pages分支未更新：使用gh-pages工具部署时，未正确执行部署命令，导致该分支仍保留旧的build产物。

对应的解决方法 #

• 同步build产物到远程仓库

  1. 执行npm run build生成最新静态文件。
  2. 执行git add build/将build文件夹加入暂存。
  3. 提交改动：git commit -m "update build artifacts"。
  4. 推送到远程主分支：git push origin main（替换为你的实际分支名）。

• 清除缓存

  • 浏览器强制刷新：Windows/Linux按Ctrl+Shift+R，Mac按Cmd+Shift+R，跳过本地缓存加载最新内容。
  • 确保资源哈希生效：create-react-app默认会在build后的静态文件名中添加哈希（如main.abc123.js），不要修改这个默认行为，确保每次更新后资源路径唯一，避免CDN缓存。

• 检查并修正部署配置

  1. 进入GitHub仓库的Settings页面，找到Pages选项。
  2. 确认Source区域的Branch选择了正确的分支和目录（比如main分支的/docs文件夹，或gh-pages分支的根目录）。
  3. 修改配置后等待5-10分钟，让GitHub完成重新部署。

• 配置homepage字段
  在package.json中添加：

  "homepage": "https://你的用户名.github.io/你的仓库名/"
  

  替换为实际的GitHub Pages地址，然后重新执行npm run build并推送build文件夹。

• 重新用gh-pages工具部署

  1. 安装依赖：npm install gh-pages --save-dev。
  2. 在package.json的scripts中添加：

     "predeploy": "npm run build",
     "deploy": "gh-pages -d build"
     

  3. 执行npm run deploy，该命令会自动完成build并将产物推送到gh-pages分支，之后确认GitHub Pages配置选择了该分支。

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