✨个人主页：编程的一拳超人

⛺️ 欢迎关注：👍点赞 📢留言 😍收藏

于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。

GitHub 双仓库静态部署完整配置手册（适配你的项目）

本手册针对你的两个仓库量身定制，全程按步骤操作即可实现「源码私有、站点公开」的自动化部署。

• 私有源码仓库：https://github.com/qiekuo/HongyunX-Agent-Web
  • 作用：存放完整前端项目源码，日常开发提交，源码不对外公开
• 公开部署仓库：https://github.com/qiekuo/HongyunX-Agent-Web-Deploy
  • 作用：仅存放编译后的 dist 静态文件，开启 GitHub Pages 对外提供访问
• 最终访问地址：https://qiekuo.github.io/HongyunX-Agent-Web-Deploy/
• 工作原理：向私有仓库推送代码 → GitHub 云端自动构建打包 → 将产物自动推送到公开仓库的 gh-pages 分支 → GitHub Pages 读取该分支对外展示

一、前期准备

1. 确认两个仓库已创建：
   • 私有仓库HongyunX-Agent-Web：已上传你的前端项目源码，包含package.json、vite.config.ts等工程文件
   • 公开仓库HongyunX-Agent-Web-Deploy：初始空仓库状态即可，无需手动上传任何代码
2. 本地前端项目可正常执行npm install和npm run build，能生成dist目录
3. 你拥有该 GitHub 账号的完整操作权限

二、步骤1：生成个人访问令牌（PAT）

该令牌用于让私有仓库的自动化流程，获得向公开部署仓库推送代码的权限，全程只需要生成一次。

1. 登录 GitHub，点击右上角头像 → 选择Settings（设置）
2. 左侧菜单拉到最底部，找到Developer settings（开发者设置）并点击
3. 左侧菜单选择Personal access tokens→ 点击下级的Tokens (classic)
4. 点击右上角Generate new token→ 选择Generate new token (classic)
5. 按以下参数填写：
   • Note（备注）：填写HongyunX-Deploy-Token（方便后续识别用途）
   • Expiration（有效期）：建议选择No expiration（永久有效；若注重安全可设置为 90 天，到期后重新生成）
   • Select scopes（权限范围）：只勾选最上方的repo大类（勾选后会自动选中 repo 下的所有子项）
6. 拉到页面最底部，点击Generate token生成令牌
7. ⚠️关键操作：生成后立刻复制完整的令牌字符串（以ghp_开头），该页面刷新后将不再显示，丢失只能重新生成

三、步骤2：私有源码仓库配置密钥

将上一步生成的令牌存入私有仓库的加密密钥中，避免明文泄露。

1. 打开你的私有源码仓库：https://github.com/qiekuo/HongyunX-Agent-Web
2. 顶部菜单点击Settings（设置）
3. 左侧菜单找到Secrets and variables→ 点击下级的Actions
4. 点击右侧New repository secret（新建仓库密钥）
5. 填写参数：
   • Name（密钥名称）：严格填写DEPLOY_TOKEN（大小写必须完全一致，后续工作流会引用这个名称）
   • Secret（密钥值）：粘贴上一步复制的完整 PAT 令牌字符串
6. 点击Add secret保存，保存后密钥值无法再次查看，只会显示名称

四、步骤3：私有仓库编写自动化工作流

在你的本地前端项目中创建工作流配置文件，提交后即可实现 push 代码自动部署。

4.1 创建文件

在项目根目录下，按层级新建文件夹和文件：

你的项目根目录 └── .github └── workflows └── deploy-to-public.yml

注意：.github是点开头的隐藏文件夹，名称必须完全一致，不能少了开头的点。

4.2 完整配置代码

将以下内容完整复制到deploy-to-public.yml文件中，无需修改任何内容，已适配你的仓库信息：

name:自动构建并部署到公开仓库# 触发条件：向 main 分支推送代码时自动执行on:push:branches:[main]# 工作流默认权限：仅读取源码permissions:contents:readjobs:build-deploy:runs-on:ubuntu-lateststeps:# 步骤1：拉取私有仓库的源代码-name:检出项目源码uses:actions/checkout@v4# 步骤2：配置 Node.js 运行环境-name:配置 Node.js 环境uses:actions/setup-node@v4with:node-version:22cache:npm# 开启依赖缓存，加快后续构建速度# 步骤3：安装项目依赖-name:安装项目依赖run:npm ci# 比 npm install 更严格，确保依赖版本与 lock 文件一致# 步骤4：执行生产环境构建打包-name:构建生产环境产物run:npm run build# 生成 dist 目录# 步骤5：将 dist 目录推送到公开部署仓库的 gh-pages 分支-name:推送静态产物到部署仓库uses:peaceiris/actions-gh-pages@v4with:# 目标公开仓库（用户名/仓库名 格式）external_repository:qiekuo/HongyunX-Agent-Web-Deploy# 引用我们配置的密钥personal_token:${{secrets.DEPLOY_TOKEN}}# 要推送的本地产物目录publish_dir:./dist# 目标仓库的分支名publish_branch:gh-pages# 提交记录信息，方便追溯版本commit_message:"自动部署: ${{ github.sha }}"# 自动添加 .nojekyll 文件，防止 GitHub 过滤下划线开头的资源enable_jekyll:false

4.3 提交文件到仓库

将.github文件夹及内部文件，提交到本地 Git 并推送到私有仓库的main分支。

五、步骤4：前端项目部署适配（必做，否则白屏/404）

GitHub Pages 项目站点是二级路径，必须修改项目基础路径，否则静态资源会加载失败。

5.1 Vite 基础路径配置

打开项目中的vite.config.ts（或vite.config.js），添加base配置：

import{defineConfig}from'vite'exportdefaultdefineConfig({// 必须与公开部署仓库名完全一致，首尾都带斜杠，大小写严格匹配base:'/HongyunX-Agent-Web-Deploy/',// 下方保留你原有的其他配置（plugins、server 等）// plugins: [vue()],// ...})

原理说明：GitHub Pages 项目站点的根路径是域名/仓库名/，如果不配置 base，项目会默认从根路径加载资源，导致 js/css 文件 404，页面空白。

5.2 SPA 路由刷新 404 修复

如果你的项目使用了 Vue Router / React Router 的 history 模式，刷新页面会出现 404，按以下方式修复：

1. 在项目的public目录下新建文件404.html
2. 将index.html的全部内容完整复制到404.html中
3. 构建打包时，该文件会自动进入 dist 目录

原理说明：GitHub Pages 遇到不存在的路径时会返回 404.html，我们让它和 index.html 内容一致，前端路由就能正常接管页面。

5.3 关于 .nojekyll 文件

上述工作流配置中enable_jekyll: false会自动在部署仓库生成.nojekyll空文件，无需手动添加。它的作用是关闭 GitHub 默认的 Jekyll 解析，防止_assets等下划线开头的文件夹被过滤。

六、步骤5：公开部署仓库开启 GitHub Pages

1. 打开公开部署仓库：https://github.com/qiekuo/HongyunX-Agent-Web-Deploy
2. 顶部菜单点击Settings（设置）
3. 左侧菜单找到Pages
4. 在Build and deployment区域按以下选择：
   • Source（来源）：选择Deploy from a branch（从分支部署）
   • Branch（分支）：
     • 第一个下拉框：暂时可能看不到gh-pages分支（第一次构建后才会自动创建），可先选main，等第一次构建完成后再回来修改
     • 第二个下拉框：选择/ (root)（根目录）
5. 点击Save保存

说明：第一次工作流执行成功后，会自动在公开仓库创建gh-pages分支。创建完成后，请回到此页面，将 Branch 切换为gh-pages，确保线上站点只读取部署产物，不受 main 分支文件影响。

七、步骤6：首次触发部署与结果验证

7.1 触发构建

将前面修改的vite.config.ts、新增的.github工作流、public/404.html全部提交并推送到私有仓库的main分支。

7.2 查看构建状态

1. 打开私有源码仓库 → 顶部菜单点击Actions
2. 列表中会出现一条正在运行的工作流，名称为「自动构建并部署到公开仓库」
3. 点击进入可以查看每一步的执行日志，绿色对勾代表成功，红色叉号代表失败，失败时可点击对应步骤查看报错详情

7.3 验证站点访问

工作流全部执行成功后，等待 1~3 分钟（GitHub Pages 缓存更新需要时间），在浏览器访问：

https://qiekuo.github.io/HongyunX-Agent-Web-Deploy/

页面正常加载即代表部署成功。

八、步骤7：部署仓库安全加固（推荐）

为防止误操作篡改线上产物，建议给公开仓库的部署分支添加保护规则。

1. 打开公开部署仓库 →Settings→ 左侧Branches
2. 点击Add branch protection rule（添加分支保护规则）
3. 填写配置：
   • Branch name pattern：填写gh-pages
   • 勾选Do not allow force pushes（禁止强制推送覆盖历史代码）
   • 勾选Do not allow deletions（禁止删除该分支）
4. 拉到底部点击Create保存

九、日常开发流程

配置完成后，日常开发无需额外操作：

1. 本地编写代码
2. 提交并推送到私有仓库main分支
3. 等待 1~2 分钟自动构建部署完成
4. 刷新线上页面查看更新

十、全场景问题排查手册

1. 工作流执行失败，报 403 权限错误

• 检查 PAT 令牌是否勾选了完整的repo权限
• 检查私有仓库 Secrets 的名称是否严格为DEPLOY_TOKEN，大小写一致
• 检查 PAT 令牌是否已过期，可重新生成替换
• 确认external_repository填写格式为用户名/仓库名，不要写完整 URL

2. 页面打开空白，控制台报 css/js 404

• 99% 是vite.config.ts中base配置错误
• 必须严格写成/HongyunX-Agent-Web-Deploy/，首尾斜杠不能丢，大小写和仓库名完全一致
• 修改后重新提交代码，等待重新部署

3. 页面刷新后出现 404

• 确认public目录下已添加404.html，且内容与index.html完全一致
• 确认文件已提交并重新部署

4. 公开仓库看不到 gh-pages 分支

• 说明工作流还没执行成功，去私有仓库的 Actions 页面查看报错
• 常见失败原因：项目本地 build 就报错、依赖安装失败、package.json 里没有build脚本

5. 样式、图片资源加载不出来

• 检查资源引用路径是否使用了绝对路径/xxx，项目级部署请使用相对路径
• 确认base配置正确，Vite 会自动根据 base 处理静态资源路径