一、双仓库部署架构说明

早期采用 Hexo 博客经典双仓库 CI/CD 架构：

  • 源码仓库：存放 Hexo 源码、配置、Markdown 文章，日常开发与提交

  • Pages 静态仓库：用户名.github.io 专属仓库，用于托管最终生成的静态页面、对外提供博客访问服务

期望实现：本地推送源码仓库 main 分支 → GitHub Actions 自动构建静态资源 → 跨仓库自动发布到 Pages 仓库，完成博客更新。

二、核心问题：跨仓库部署 403 权限拒绝

配置完成后，流水线持续报错：

remote: Permission to xxx.github.io.git denied to github-actions[bot].

fatal: unable to access ... The requested URL returned error: 403

问题根因：

  1. GitHub 内置的 GITHUB_TOKEN仅对当前仓库有权限，无法跨仓库推送代码；

  2. 双仓库模式下，Actions 机器人需要操作另一个独立仓库，直接触发权限拦截，返回 403；

  3. 即使两个仓库归属同一账号、存在 Fork 关联，Fork 工作流也无法解决跨仓写入权限问题，官方安全策略严格限制跨仓库资源写入。

三、双仓库模式衍生痛点

1. 权限配置繁琐、极易出错

必须手动创建永久 PAT 令牌、配置 repo 全量权限、在源码仓库配置 Secrets，步骤冗余。一旦令牌过期、权限缺失、Secret 配置错误，流水线直接挂掉，无兜底机制。

2. 分支保护冲突，部署规则受限

Pages 仓库默认 main 分支受系统保护，禁止同分支覆盖写入。必须额外修改部署分支为 gh-pages，同时同步修改 GitHub Pages 访问分支配置，增加大量适配成本。

3. 故障排查成本高

跨仓库报错模糊，常见 403 权限拒绝、git 128 异常、分支冲突、资源路径404等连锁问题，新手极难定位根因，整体稳定性极差。

四、最终解决方案：弃用双仓库，改用单仓库部署

对比踩坑成本后，放弃双仓库架构，切换为单仓库标准工作流：

  • 唯一仓库：用户名.github.io

  • main 分支：存放全部 Hexo 源码、文章、配置（日常迭代提交）

  • gh-pages 分支：Actions 自动生成、自动推送静态资源

优势：

  1. 无需手动配置 PAT 令牌，内置 GITHUB_TOKEN 完全够用；

  2. 无跨仓库权限问题，彻底解决 403 报错；

  3. 流程极简、社区标准、稳定性极高，几乎零运维；

  4. 分支隔离规范，源码与静态资源互不干扰，无覆盖风险。

五、总结

Hexo 双仓库自动化部署方案理论可行，实际落地坑极多，核心瓶颈为 GitHub 跨仓库权限机制限制，衍生大量配置、权限、分支冲突问题。对于个人博客场景，单仓库 + main/gh-pages 双分支隔离 是最优、最稳、最省心的 CI/CD 方案。

（注：文档部分内容可能由 AI 生成）