You need to enable JavaScript to run this app. 为什么我的Github Pages自定义域名每次部署后总会被重置?
优惠活动
大模型
产品
解决方案
定价
更多

为什么我的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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.24 09:54:03