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

✨个人主页编程的一拳超人⛺️ 欢迎关注点赞 留言 收藏于高山之巅方见大河奔涌于群峰之上更觉长风浩荡。GitHub 双仓库静态部署完整配置手册适配你的项目一、前期准备二、步骤1生成个人访问令牌PAT三、步骤2私有源码仓库配置密钥四、步骤3私有仓库编写自动化工作流4.1 创建文件4.2 完整配置代码4.3 提交文件到仓库五、步骤4前端项目部署适配必做否则白屏/4045.1 Vite 基础路径配置5.2 SPA 路由刷新 404 修复5.3 关于 .nojekyll 文件六、步骤5公开部署仓库开启 GitHub Pages七、步骤6首次触发部署与结果验证7.1 触发构建7.2 查看构建状态7.3 验证站点访问八、步骤7部署仓库安全加固推荐九、日常开发流程十、全场景问题排查手册1. 工作流执行失败报 403 权限错误2. 页面打开空白控制台报 css/js 4043. 页面刷新后出现 4044. 公开仓库看不到 gh-pages 分支5. 样式、图片资源加载不出来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 读取该分支对外展示一、前期准备确认两个仓库已创建私有仓库HongyunX-Agent-Web已上传你的前端项目源码包含package.json、vite.config.ts等工程文件公开仓库HongyunX-Agent-Web-Deploy初始空仓库状态即可无需手动上传任何代码本地前端项目可正常执行npm install和npm run build能生成dist目录你拥有该 GitHub 账号的完整操作权限二、步骤1生成个人访问令牌PAT该令牌用于让私有仓库的自动化流程获得向公开部署仓库推送代码的权限全程只需要生成一次。登录 GitHub点击右上角头像 → 选择Settings设置左侧菜单拉到最底部找到Developer settings开发者设置并点击左侧菜单选择Personal access tokens→ 点击下级的Tokens (classic)点击右上角Generate new token→ 选择Generate new token (classic)按以下参数填写Note备注填写HongyunX-Deploy-Token方便后续识别用途Expiration有效期建议选择No expiration永久有效若注重安全可设置为 90 天到期后重新生成Select scopes权限范围只勾选最上方的repo大类勾选后会自动选中 repo 下的所有子项拉到页面最底部点击Generate token生成令牌⚠️关键操作生成后立刻复制完整的令牌字符串以ghp_开头该页面刷新后将不再显示丢失只能重新生成三、步骤2私有源码仓库配置密钥将上一步生成的令牌存入私有仓库的加密密钥中避免明文泄露。打开你的私有源码仓库https://github.com/qiekuo/HongyunX-Agent-Web顶部菜单点击Settings设置左侧菜单找到Secrets and variables→ 点击下级的Actions点击右侧New repository secret新建仓库密钥填写参数Name密钥名称严格填写DEPLOY_TOKEN大小写必须完全一致后续工作流会引用这个名称Secret密钥值粘贴上一步复制的完整 PAT 令牌字符串点击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/checkoutv4# 步骤2配置 Node.js 运行环境-name:配置 Node.js 环境uses:actions/setup-nodev4with: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-pagesv4with:# 目标公开仓库用户名/仓库名 格式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:false4.3 提交文件到仓库将.github文件夹及内部文件提交到本地 Git 并推送到私有仓库的main分支。五、步骤4前端项目部署适配必做否则白屏/404GitHub Pages 项目站点是二级路径必须修改项目基础路径否则静态资源会加载失败。5.1 Vite 基础路径配置打开项目中的vite.config.ts或vite.config.js添加base配置import{defineConfig}fromviteexportdefaultdefineConfig({// 必须与公开部署仓库名完全一致首尾都带斜杠大小写严格匹配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按以下方式修复在项目的public目录下新建文件404.html将index.html的全部内容完整复制到404.html中构建打包时该文件会自动进入 dist 目录原理说明GitHub Pages 遇到不存在的路径时会返回 404.html我们让它和 index.html 内容一致前端路由就能正常接管页面。5.3 关于 .nojekyll 文件上述工作流配置中enable_jekyll: false会自动在部署仓库生成.nojekyll空文件无需手动添加。它的作用是关闭 GitHub 默认的 Jekyll 解析防止_assets等下划线开头的文件夹被过滤。六、步骤5公开部署仓库开启 GitHub Pages打开公开部署仓库https://github.com/qiekuo/HongyunX-Agent-Web-Deploy顶部菜单点击Settings设置左侧菜单找到Pages在Build and deployment区域按以下选择Source来源选择Deploy from a branch从分支部署Branch分支第一个下拉框暂时可能看不到gh-pages分支第一次构建后才会自动创建可先选main等第一次构建完成后再回来修改第二个下拉框选择/ (root)根目录点击Save保存说明第一次工作流执行成功后会自动在公开仓库创建gh-pages分支。创建完成后请回到此页面将 Branch 切换为gh-pages确保线上站点只读取部署产物不受 main 分支文件影响。七、步骤6首次触发部署与结果验证7.1 触发构建将前面修改的vite.config.ts、新增的.github工作流、public/404.html全部提交并推送到私有仓库的main分支。7.2 查看构建状态打开私有源码仓库 → 顶部菜单点击Actions列表中会出现一条正在运行的工作流名称为「自动构建并部署到公开仓库」点击进入可以查看每一步的执行日志绿色对勾代表成功红色叉号代表失败失败时可点击对应步骤查看报错详情7.3 验证站点访问工作流全部执行成功后等待 1~3 分钟GitHub Pages 缓存更新需要时间在浏览器访问https://qiekuo.github.io/HongyunX-Agent-Web-Deploy/页面正常加载即代表部署成功。八、步骤7部署仓库安全加固推荐为防止误操作篡改线上产物建议给公开仓库的部署分支添加保护规则。打开公开部署仓库 →Settings→ 左侧Branches点击Add branch protection rule添加分支保护规则填写配置Branch name pattern填写gh-pages勾选Do not allow force pushes禁止强制推送覆盖历史代码勾选Do not allow deletions禁止删除该分支拉到底部点击Create保存九、日常开发流程配置完成后日常开发无需额外操作本地编写代码提交并推送到私有仓库main分支等待 1~2 分钟自动构建部署完成刷新线上页面查看更新十、全场景问题排查手册1. 工作流执行失败报 403 权限错误检查 PAT 令牌是否勾选了完整的repo权限检查私有仓库 Secrets 的名称是否严格为DEPLOY_TOKEN大小写一致检查 PAT 令牌是否已过期可重新生成替换确认external_repository填写格式为用户名/仓库名不要写完整 URL2. 页面打开空白控制台报 css/js 40499% 是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 处理静态资源路径