使用npm gh-pages模块部署GitHub Pages的不稳定问题

核心问题 #

1. npm run deploy日志显示"Published"但gh-pages分支无更新
2. 上次成功部署后CSS加载失效

一、部署成功但分支未更新的解决方法 #

1. 修正deploy脚本，强制指定远程仓库与分支 #

原脚本依赖缓存的仓库配置，可能出现静默推送失败。修改deploy脚本为：

"deploy": "npx gh-pages -d dist -r git@github.com:JRiggles/jriggles.github.io.git -b gh-pages"

• 使用SSH地址替代HTTPS，避免HTTPS认证缓存问题
• 明确指定推送分支为gh-pages，消除分支歧义

2. 彻底清理gh-pages缓存 #

除了运行预设的清理脚本，手动删除缓存目录确保无残留：

rm -rf node_modules/.cache/gh-pages

3. 确保predeploy阶段构建无静默失败 #

在predeploy开头添加set -e，让脚本在构建失败时立即终止，避免后续无效部署：

"predeploy": "set -e && rm -rf .parcel-cache && rm -rf dist && npx parcel build src/index.pug --public-url '/' && cp CNAME ./dist && npm run 'copy static files'"

二、CSS失效问题的根本解决 #

修正public-url参数 #

原predeploy中--public-url 'https://github.com/JRiggles/jriggles.github.io'是错误的：GitHub Pages资源路径应基于自定义域名的根目录，而非GitHub仓库地址。修改为：

--public-url '/'

此设置会让Parcel生成的资源路径为/css/xxx.css，匹配自定义域名jriggl.es的根路径，确保CSS/JS能正确加载。

验证步骤 #

1. 单独执行npm run predeploy，检查dist目录：
   • 确认静态文件、CNAME已复制到位
   • 查看HTML中的资源路径是否为根路径（如<link href="/css/main.css">）
2. 进入gh-pages缓存目录，手动验证git状态：

   cd node_modules/.cache/gh-pages/https!github.com!JRiggles!jriggles.github.io.git
   git log # 查看是否有新提交
   git push origin gh-pages # 手动推送，观察是否有明确错误
   

站点对比截图 #

• 本地开发正常效果：
  
• 部署后CSS失效效果：
  

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