为什么我的Github Pages自定义域名每次部署后总会被重置?
gh-pages 部署时自定义域名被重置的永久解决方案
核心原因
gh-pages npm包默认采用全量替换的方式更新目标部署分支的根目录内容。GitHub Pages的自定义域名配置是和部署分支根目录下的CNAME文件强绑定的——一旦这个文件在全量部署过程中被覆盖删除,仓库Pages设置页里的自定义域名配置就会自动被清空,站点回退到默认的user.github.io/repo访问地址。
具体操作方案
方案一:手动维护CNAME文件(零脚本,适配所有项目)
- 在项目的静态资源输出目录(即gh-pages命令中
-d参数指向的目录,常见为dist、build、public文件夹)中,创建无任何后缀的CNAME文件 - 在文件中仅写入你的自定义域名,例如
myblog.example.com,不要添加http/https前缀、结尾路径等额外内容 - 检查构建流程的过滤规则:确认Webpack、Vite等构建工具的静态资源拷贝配置,不会将
CNAME文件排除在最终打包输出之外
配置完成后,每次执行gh-pages部署时,CNAME文件会随其他静态资源一同推送到部署分支的根目录,GitHub Pages会自动识别该文件并匹配对应的自定义域名设置,不会出现配置被重置的问题。
方案二:脚本自动生成CNAME(无需手动维护,适配CI/CD流程)
如果不想手动管理CNAME文件,可以利用npm脚本的前置钩子,在每次部署前自动生成目标文件:
- 打开项目根目录的
package.json文件,修改scripts字段的部署相关配置,利用gh-pages内置的predeploy前置执行逻辑,在部署环节前自动完成CNAME文件生成,示例配置:{ "scripts": { "build": "项目静态资源构建命令", "predeploy": "npm run build && echo 'myblog.example.com' > ./dist/CNAME", "deploy": "gh-pages -d dist" } } - 配置完成后,每次执行
npm run deploy命令,会自动按顺序完成资源构建、CNAME文件写入、全量部署的全流程,不需要手动介入修改文件。
效果校验
部署完成后可通过两个维度确认配置生效:
- 查看对应部署分支的根目录,确认根路径下存在
CNAME文件,文件内容和设置的自定义域名完全一致 - 打开仓库的Pages设置页面,自定义域名输入框的内容不会被清空,站点访问不会自动跳回默认的
user.github.io/repo地址
内容的提问来源于stack exchange,提问作者Jim
相关产品推荐
相关产品推荐

