1. 项目概述从静态托管到国内访问优化如果你是一名开发者、博主或者只是想找个免费又稳定的地方放你的个人主页、项目文档那么 GitHub Pages 和 Gitee Pages 这两个名字你一定不陌生。前者是全球最大的代码托管平台 GitHub 提供的静态网站托管服务后者是国内代码托管平台 Gitee 提供的同类服务。听起来很美对吧但实际操作起来尤其是当你需要兼顾国内外的访问速度或者想把项目从 GitHub 同步到 Gitee 时坑可不少。我自己就曾为了一个简单的个人博客在两边反复折腾特别是遇到 Gitee Pages 部署后页面一片空白控制台疯狂报样式和 JS 文件 404 错误时那种抓狂的感觉记忆犹新。这篇文章就是把我踩过的坑、试过的方案以及最终稳定运行的配置和更新流程毫无保留地分享出来。这不仅仅是一个“配置教程”更是一个“避坑指南”。我们会从最基础的仓库创建、Pages 服务开启讲起深入到双平台同步更新的高效工作流并重点攻克那个令人头疼的“Gitee Pages 访问空白、资源 404”的经典难题。无论你是前端新手还是有一定经验的开发者只要你想用这两个免费的 Pages 服务搭建点东西这篇内容都能帮你省下大量搜索和排错的时间。2. 核心思路与方案选型为何选择双平台部署在开始动手之前我们得先想清楚为什么要同时使用 GitHub Pages 和 Gitee Pages。这背后其实是一个很实际的考量访问速度与网络环境。GitHub Pages 依托于 GitHub 的全球 CDN在国外访问速度极快且与 GitHub 生态无缝集成非常适合做项目官网、技术文档或者面向国际用户的个人博客。但是由于众所周知的原因它在国内的直接访问速度时好时坏甚至可能完全无法加载这就会导致你的国内访客体验极差。Gitee Pages 作为国内服务访问速度稳定、延迟低是国内用户访问的最佳选择。然而Gitee 的 Pages 服务在某些机制上尤其是对静态资源路径的处理与 GitHub 存在差异直接照搬 GitHub 的代码往往会出现问题也就是我们标题里提到的“样式和 JS 文件 404”。因此一个理想的方案是以 GitHub 作为主仓库和开发环境利用其强大的协作和 CI/CD 生态同时将代码自动或手动同步到 Gitee利用 Gitee Pages 服务国内访问。这样既能享受 GitHub 的开发便利又能保证国内用户的访问体验。我们的教程也将围绕这个“主从同步”的思路展开。注意Gitee 的免费 Pages 服务对于开源仓库是免费的但如果你需要自定义域名等高级功能或者仓库是私有的则需要关注其最新的服务条款和收费政策。接下来我们将这个思路拆解为几个可执行的阶段环境与仓库准备在 GitHub 和 Gitee 上创建对应的仓库。本地开发环境搭建配置 Git 和基本的静态网站生成工具如 Hexo, VuePress, Docsify 等本文将以通用静态文件为例。GitHub Pages 配置与部署完成首次部署并确保其在 GitHub 上访问正常。Gitee Pages 配置与同步将代码推送到 Gitee 并开启 Pages此时很可能会遇到空白页问题。Gitee Pages 404 问题深度解决分析问题根源并提供多种经过验证的解决方案。自动化同步与更新流程建立一套高效的、可持续的更新机制。3. 基础环境与仓库准备工欲善其事必先利其器。在开始写第一行代码之前我们需要把“战场”布置好。3.1 创建 GitHub 仓库登录你的 GitHub 账号。点击右上角 “” 号选择 “New repository”。填写仓库名。这里有一个关键点如果你想使用https://[你的用户名].github.io这样的专属域名访问那么仓库名必须严格设置为[你的用户名].github.io。例如你的用户名是zhangsan那么仓库名就是zhangsan.github.io。如果你想为某个特定项目创建 Pages访问地址为https://[你的用户名].github.io/[仓库名]那么仓库名可以任意。选择 “Public”公开因为 GitHub Pages 仅支持公开仓库免费使用。建议勾选 “Add a README file”方便后续克隆。点击 “Create repository” 完成创建。3.2 创建 Gitee 仓库登录你的 Gitee 账号。点击右上角 “” 号选择 “新建仓库”。填写仓库名。为了便于管理我强烈建议 Gitee 的仓库名与 GitHub 的保持完全一致。例如在 GitHub 上是zhangsan.github.io在 Gitee 上也创建同名仓库zhangsan.github.io。当然你也可以用其他名字但同步时会稍麻烦一些。其他设置如“公开”、“初始化 README”等与 GitHub 类似。点击“创建”完成。3.3 本地 Git 环境配置如果你的电脑上还没有安装 Git请先去官网下载安装。安装后打开终端Windows 用 CMD 或 PowerShellMac/Linux 用 Terminal进行全局配置git config --global user.name 你的用户名 git config --global user.email 你的邮箱这个用户名和邮箱最好与你的 GitHub/Gitee 账号一致方便提交记录关联。接下来将刚刚创建的两个远程仓库都克隆到本地或者与本地已有的项目关联。这里我推荐一种更清晰的管理方式以 GitHub 仓库为主将其克隆到本地然后将 Gitee 仓库添加为第二个远程地址。假设你的 GitHub 仓库地址是https://github.com/zhangsan/zhangsan.github.io.gitGitee 仓库地址是https://gitee.com/zhangsan/zhangsan.github.io.git。# 1. 克隆 GitHub 主仓库到本地 git clone https://github.com/zhangsan/zhangsan.github.io.git cd zhangsan.github.io # 2. 添加 Gitee 仓库作为第二个远程源通常命名为 gitee 以示区分 git remote add gitee https://gitee.com/zhangsan/zhangsan.github.io.git # 3. 查看远程仓库配置此时应该看到 origin (GitHub) 和 gitee 两个远程地址 git remote -v这样你的本地仓库就同时关联了 GitHub 和 Gitee。你可以用git push origin main推送到 GitHub用git push gitee main推送到 Gitee。4. GitHub Pages 配置与首次部署GitHub Pages 的配置相对简单直观大部分工作可以在仓库的 Web 界面完成。4.1 准备你的网站内容进入你刚克隆下来的本地仓库文件夹。你的网站内容需要放在这个目录下。对于最简单的 Pages你只需要一个index.html文件。但通常我们的网站会更复杂包含 CSS、JS、图片等资源。一个典型的静态网站结构可能如下zhangsan.github.io/ ├── index.html ├── css/ │ └── style.css ├── js/ │ └── main.js └── images/ └── logo.png请确保你的index.html中引用的资源路径是相对路径。例如link relstylesheet href./css/style.css script src./js/main.js/script img src./images/logo.png altlogo使用相对路径以./或../开头是保证 Pages 服务在不同路径下都能正确找到资源的关键也是后续解决 Gitee 问题的前提。4.2 开启 GitHub Pages 功能将你的网站代码提交并推送到 GitHub 仓库的main分支或master分支取决于你的默认分支名。git add . git commit -m Initial commit with website files git push origin main在 GitHub 上打开你的仓库页面点击顶部菜单的 “Settings”。在左侧边栏找到 “Pages” 选项。在 “Source” 部分选择你的部署分支通常是main或master和部署文件夹如果网站文件在根目录就选/ (root)如果使用了 Jekyll 等静态站点生成器可能默认是/(root)或/docs。点击 “Save”。等待几分钟通常不到一分钟GitHub Actions 会自动构建和部署你的网站。刷新页面后你会看到一个绿色的提示框里面包含你的网站链接格式为https://[用户名].github.io或https://[用户名].github.io/[仓库名]。点击这个链接你的网站应该能正常显示所有样式和功能都完好。实操心得第一次部署后如果遇到 404别急。可能是构建还没完成等个两三分钟再刷新。如果还是不行检查你的index.html文件名是否正确大小写敏感以及是否真的推送到了你设置的分支。5. Gitee Pages 配置与同步问题初现当 GitHub Pages 顺利运行后我们开始同步到 Gitee。这一步是“踩坑”的开始。5.1 推送代码到 Gitee还记得我们之前添加的gitee远程仓库吗现在把代码推过去git push gitee main如果 Gitee 仓库是空的这条命令会把本地main分支的完整历史推上去。如果 Gitee 仓库已有内容比如初始化了 README可能会冲突需要先拉取合并git pull gitee main --allow-unrelated-histories解决冲突后再推送。5.2 开启 Gitee Pages 服务在 Gitee 上打开你的仓库页面。在仓库导航栏中找到 “服务” - “Gitee Pages”。你会进入 Pages 部署页面。与 GitHub 类似你需要选择部署分支如main和部署目录如/。点击 “启动” 或 “更新”。Gitee Pages 的部署速度也很快。部署成功后页面会给出你的访问地址通常是https://[用户名].gitee.io/[仓库名]。5.3 遭遇“空白页”与“404”此时如果你兴冲冲地打开 Gitee Pages 的链接很大概率会看到以下情况之一页面一片空白查看网页源代码右键 - 查看网页源代码HTML 结构是完整的但页面就是没渲染。控制台报错打开浏览器的开发者工具F12切换到 “Console” 标签页你会看到一堆红色的错误核心内容是Failed to load resource: the server responded with a status of 404 (Not Found)指向你的style.css、main.js等文件。问题根源分析这个问题是 Gitee Pages 与 GitHub Pages 在路径解析策略上的差异导致的。GitHub Pages非常智能。无论你的仓库是[用户名].github.io这种用户页面还是普通的项目页面它都会自动将网站根目录/映射到你的仓库根目录。你的相对路径./css/style.css能正确指向https://[用户名].github.io/css/style.css。Gitee Pages的路径处理相对“死板”。对于项目页面即非[用户名].gitee.io这种独立域名它默认会将你的网站部署在一个子路径下。例如你的仓库名是myblog那么访问地址是https://[用户名].gitee.io/myblog。但你的 HTML 文件里写的资源路径./css/style.css在浏览器中会被解析为相对于当前页面 URL 的路径即https://[用户名].gitee.io/myblog/css/style.css。然而Gitee Pages 服务器可能期望你使用绝对路径/myblog/css/style.css或者它没有正确地将请求路由到仓库的根目录从而导致 404。简单说就是基础路径Base URL不匹配。你的代码假设网站运行在根目录但 Gitee 把它放在了子目录里。6. Gitee Pages 404 问题解决方案大全亲测有效针对上述根源我尝试并总结了以下几种解决方案你可以根据你的项目类型和复杂度来选择。6.1 方案一修改 Gitee Pages 部署目录最快捷这是最简单粗暴但往往有效的办法。Gitee Pages 允许你选择部署分支下的某个子目录作为网站根目录。操作步骤在你的仓库根目录下创建一个新文件夹例如叫做dist或public。将你所有的网站文件index.html,css/,js/,images/等移动到这个dist文件夹内。注意是移动不是复制意味着仓库根目录下除了dist文件夹和必要的配置文件如.gitignore,README.md不应该有其他网站源文件。修改dist/index.html中的资源引用路径。因为现在index.html在dist目录下它引用的./css/style.css仍然在dist/css/下所以相对路径不需要改变。提交并推送到 Gitee 仓库。git add . git commit -m “Move site files to dist folder for Gitee Pages” git push gitee main进入 Gitee 仓库的 “Pages” 服务页面。在“部署目录”中选择/dist。点击“更新”。原理与效果这个方法的原理是“欺骗” Gitee Pages。我们告诉 Gitee“我的网站根目录不是仓库根目录而是/dist子目录”。当 Gitee Pages 服务构建时它会将https://[用户名].gitee.io/[仓库名]直接映射到我们仓库里的/dist目录。此时/dist目录在服务器上就被当作根目录/来对待其内部的相对路径./css/style.css就能被正确解析了。注意事项这个方法虽然简单但破坏了仓库的原始结构。如果你的项目需要同时在 GitHub 和 Gitee 上保持代码一致比如 GitHub 作为源Gitee 作为镜像这就很麻烦因为 GitHub Pages 也需要对应地修改部署目录。所以它更适合 Gitee 专用部署或者你能接受两地目录结构不同的情况。6.2 方案二使用配置指定基础路径推荐给静态站点生成器如果你使用的是 Hexo、VuePress、Docsify、Docusaurus 等静态站点生成器它们通常支持在配置文件中设置base或baseUrl选项。这个选项就是用来解决子目录部署问题的。以 VuePress 为例在docs/.vuepress/config.js中module.exports { base: ‘/你的仓库名/‘, // 例如仓库名是 myblog这里就填 ‘/myblog/‘ // ... 其他配置 }以 Hexo 为例在站点配置文件_config.yml中url: https://yourname.gitee.io root: /仓库名/ # 例如root: /myblog/以 Docsify 为例在index.html中加载 Docsify 的配置部分script window.$docsify { basePath: ‘/仓库名/‘, // ... 其他配置 } /script操作步骤在你的静态站点生成器配置中找到设置基础路径base, baseUrl, root, publicPath 等的选项。将其值设置为‘/你的Gitee仓库名/‘。注意仓库名是大小写敏感的且首尾要有斜杠/。重新生成静态文件。例如Hexo 用hexo clean hexo gVuePress 用npm run docs:build。将生成的静态文件通常是public、dist或.vuepress/dist目录下的所有内容拷贝到你的 Git 仓库根目录下或者你指定的 Gitee 部署目录。确保index.html在仓库根目录。提交并推送到 Gitee然后更新 Gitee Pages。原理与效果静态站点生成器在构建时会根据你设置的base路径重写所有资源链接、路由链接。生成的index.html中资源路径会从./css/style.css变成/仓库名/css/style.css这样的绝对路径相对于域名根目录。这样无论网站被部署在https://gitee.io/仓库名还是其他任何子路径下浏览器都会去域名根目录下的/仓库名/css/寻找资源而这个位置正好是 Gitee Pages 服务提供资源的地方。实操心得这是最优雅、最一劳永逸的解决方案。它从构建源头解决了路径问题并且能同时适配 GitHub Pages将base设为‘/‘和 Gitee Pages。你可以通过环境变量或不同的构建命令来为两个平台生成不同的输出。例如在package.json中设置两个脚本“deploy:github”: “vuepress build docs“ “deploy:gitee”: “cross-env BASE_URL’/repo-name/’ vuepress build docs“。6.3 方案三修改 HTML 中的资源引用路径通用但繁琐如果你的网站是纯手工编写的 HTML没有使用构建工具那么你可以直接修改 HTML 文件中的资源路径。将相对路径改为绝对路径相对于域名的根路径修改前link rel“stylesheet” href“./css/style.css”修改后link rel“stylesheet” href“/仓库名/css/style.css” !-- 或者如果你确定最终部署在仓库根目录也可以用 /css/style.css --操作步骤批量查找并替换你的index.html以及可能引用了资源的其他 HTML 文件中所有href和src属性。将类似href“./css/...”和src“./js/...”的路径替换为以/仓库名/开头的绝对路径。提交、推送、更新 Pages。原理与效果与方案二类似强制指定了资源的绝对位置绕过了浏览器基于当前页面 URL 的相对路径解析。注意事项这个方法非常直接但缺点也很明显维护成本高。你拥有两套几乎相同、只有路径不同的 HTML 文件。每次更新内容你都需要手动维护两套或者写脚本进行替换极易出错。不推荐作为长期方案仅适用于极其简单、一次性部署的页面。6.4 方案四使用 JavaScript 动态修正路径前端 Hack这是一个纯前端的解决方案通过一小段 JavaScript 代码在页面加载时动态检测并修正资源路径。操作步骤在你的index.html的head标签最顶部添加如下脚本script (function() { // 判断是否运行在 Gitee Pages 环境下 if (window.location.hostname.indexOf(‘gitee.io’) -1) { var repoName ‘你的仓库名‘; // 请修改为你的仓库名 var basePath ‘/‘ repoName ‘/‘; // 修正 link[rel“stylesheet”] 的 href document.querySelectorAll(‘link[rel“stylesheet”]‘).forEach(function(link) { var href link.getAttribute(‘href’); if (href href.startsWith(‘./’)) { link.setAttribute(‘href’, basePath href.substring(2)); } }); // 修正 script[src] 的 src (排除当前动态脚本本身) document.querySelectorAll(‘script[src]‘).forEach(function(script) { var src script.getAttribute(‘src’); if (src src.startsWith(‘./’) !script.hasAttribute(‘data-no-fix’)) { script.setAttribute(‘src’, basePath src.substring(2)); } }); // 你可以根据需要继续修正 img、a 等标签的 src 或 href // 例如修正图片 document.querySelectorAll(‘img[src]‘).forEach(function(img) { var src img.getAttribute(‘src’); if (src src.startsWith(‘./’)) { img.setAttribute(‘src’, basePath src.substring(2)); } }); } })(); /script记得将代码中的‘你的仓库名’替换成你实际的 Gitee 仓库名。原理与效果这段脚本在页面加载初期执行。它首先检查当前域名是否包含gitee.io如果是则判定为运行在 Gitee Pages。然后它遍历页面中的所有样式表和脚本标签可以根据需要扩展如果发现其路径是以./开头的相对路径就将其替换为基于仓库名的绝对路径如/myrepo/css/style.css。这样浏览器就能从正确的位置加载资源了。注意事项这是一个“补救”性质的 Hack。它有几个缺点1)依赖 JavaScript如果用户浏览器禁用了 JS页面依然会崩。2)可能有闪烁资源是在 HTML 解析后才被修正和加载的可能导致页面先以无样式状态渲染然后再突然应用样式。3)不够彻底一些通过 JS 动态加载的资源可能无法被这个脚本捕获。仅作为临时解决方案或无法修改构建流程时的备选方案。6.5 方案总结与选择建议方案适用场景优点缺点推荐指数一、改部署目录简单静态网站Gitee专用部署。操作简单无需修改代码。破坏仓库结构双平台同步麻烦。⭐⭐二、配置基础路径使用 Hexo, VuePress 等静态站点生成器。一劳永逸配置优雅源头解决。需要了解所用工具的配置。⭐⭐⭐⭐⭐三、改HTML路径纯手工HTML小项目且不考虑维护性。直接有效不依赖其他工具。维护成本极高易出错。⭐⭐四、JS动态修正临时解决或无法控制构建过程。无需改动构建流程一次注入。依赖JS可能有渲染闪烁不彻底。⭐⭐⭐我的最终选择与建议对于绝大多数项目方案二配置基础路径是最佳实践。它从构建层面解决问题干净彻底并能轻松适配多部署环境。如果你的项目没有使用静态站点生成器我强烈建议你引入一个比如 VuePress 或 Docsify它们不仅能解决路径问题还能带来更好的文档/博客编写体验。如果你坚持使用纯静态文件那么可以结合方案一和方案四。在 Gitee 上使用独立的dist目录部署方案一同时在这个dist目录的index.html中注入动态修正脚本方案四作为双保险。本地开发或 GitHub 部署则使用原始的目录结构。7. 建立高效的自动化同步与更新流程解决了部署问题我们还需要一个高效的更新流程。每次都在本地改代码然后分别push到 GitHub 和 Gitee太麻烦了。我们的目标是一次推送自动同步。7.1 使用 Git 远程仓库镜像推送这是最简单的方法。我们之前已经为本地仓库添加了两个远程地址origin(GitHub) 和gitee。我们可以配置一个命令同时推送到两个远程仓库。# 方法1依次推送 git push origin main git push gitee main # 方法2使用一条命令利用 git 的多个推送目标 # 编辑本地仓库的 .git/config 文件找到 [remote “origin”] 部分添加 gitee 的 url # 或者直接使用命令修改 git remote set-url --add --push origin https://gitee.com/zhangsan/zhangsan.github.io.git # 然后再执行 push就会同时推送到 origin 的所有 url git push origin main不过更清晰的做法是写一个简单的 Shell 脚本或批处理文件。7.2 使用 GitHub Actions 自动同步到 Gitee推荐这是更自动化、更“DevOps”的方式。原理是当代码推送到 GitHub 后利用 GitHub Actions 这个 CI/CD 工具自动将代码同步到 Gitee 仓库。操作步骤在 Gitee 生成私人令牌Private Token登录 Gitee进入【设置】-【安全设置】-【私人令牌】。点击“生成新令牌”描述可以写“GitHub Actions Sync”权限勾选projects和pull_requests的读写权限即可。生成后务必立即复制并保存好令牌字符串它只会显示一次。在 GitHub 仓库添加 Secrets打开你的 GitHub 仓库进入 【Settings】 - 【Secrets and variables】 - 【Actions】。点击 “New repository secret”。Name 填写GITEE_TOKENValue 粘贴你刚才复制的 Gitee 私人令牌。再添加一个 SecretName 为GITEE_USERValue 为你的 Gitee 用户名。创建 GitHub Actions 工作流文件在你的 GitHub 仓库根目录下创建.github/workflows/sync-to-gitee.yml文件。编写工作流配置将以下 YAML 配置复制到sync-to-gitee.yml文件中。这个配置实现了当向main分支推送代码时自动同步到 Gitee 的同名仓库。name: Sync to Gitee on: push: branches: - main # 监听 main 分支的 push 事件可根据需要改为 master jobs: sync: runs-on: ubuntu-latest steps: - name: Checkout GitHub code uses: actions/checkoutv3 with: persist-credentials: false # 重要不使用默认的 GitHub token - name: Sync to Gitee uses: wearerequired/git-mirror-actionmaster env: # 从 GitHub Secrets 中读取配置 SSH_PRIVATE_KEY: ${{ secrets.GITEE_SSH_PRIVATE_KEY }} # 可选如果使用 SSH 方式 with: # 源仓库即当前 GitHub 仓库 source-repo: “https://github.com/${{ github.repository }}.git“ # 目标仓库你的 Gitee 仓库地址 destination-repo: “https://${{ secrets.GITEE_USER }}:${{ secrets.GITEE_TOKEN }}gitee.com/${{ secrets.GITEE_USER }}/${{ github.event.repository.name }}.git“ # 如果是私有仓库可能需要 SSH 密钥这里使用 HTTPS 令牌的方式更简单注意上面的配置使用了 HTTPS 和令牌的方式。如果你的仓库是公开的这通常没问题。如果遇到权限问题可以考虑使用 SSH 密钥对的方式那需要在 Gitee 添加部署公钥并在 GitHub Secrets 中配置私钥GITEE_SSH_PRIVATE_KEY。提交并推送这个工作流文件git add .github/workflows/sync-to-gitee.yml git commit -m “Add GitHub Actions workflow for syncing to Gitee” git push origin main验证推送完成后到你的 GitHub 仓库的 “Actions” 标签页你会看到一个新的工作流正在运行或已经完成。如果成功你的代码会在几分钟内出现在 Gitee 仓库中。你只需要再去 Gitee 的 Pages 服务页面点一下“更新”网站就同步部署了。实操心得使用 GitHub Actions 自动同步是最佳实践。它实现了“一次推送两地同步”。你只需要关心向 GitHub 提交代码剩下的同步和 Gitee Pages 的更新甚至可以配置 Actions 自动触发 Gitee Pages 构建都可以自动化。这极大提升了双平台维护的效率。唯一需要手动操作的可能就是去 Gitee 点一下“更新” Pages这部分其实也可以通过 Gitee 的 API 在 Actions 中进一步自动化但步骤稍复杂。7.3 可选自动触发 Gitee Pages 部署Gitee 提供了 Pages 构建的 API我们可以在上面的 GitHub Actions 工作流中在同步代码后调用这个 API 自动触发 Gitee Pages 的更新实现完全自动化。你需要在 Gitee 的私人令牌中确保勾选了deployments权限。在 GitHub Actions 工作流中添加一个新的 step使用curl或专门的 Action 来调用 Gitee API。示例步骤接在上述syncjob 的 steps 之后- name: Trigger Gitee Pages Build run: | curl -X POST \ -H “Content-Type: application/json;charsetUTF-8” \ -H “Authorization: token ${{ secrets.GITEE_TOKEN }}” \ “https://gitee.com/api/v5/repos/${{ secrets.GITEE_USER }}/${{ github.event.repository.name }}/pages/builds”这样整个流程就完全无人值守了GitHub Push - Actions 同步代码到 Gitee - Actions 触发 Gitee Pages 构建 - 网站更新。8. 常见问题与排查技巧实录即使按照教程操作你可能还是会遇到一些奇怪的问题。这里记录了我遇到的一些典型情况及其解决方法。8.1 Gitee Pages 更新后访问的还是旧页面现象代码已经同步Gitee Pages 也显示“更新成功”但浏览器访问看到的还是老版本甚至清空缓存也没用。排查检查构建日志在 Gitee Pages 服务页面查看“部署历史”或“构建日志”确认最新的构建是否真的成功完成有没有报错。检查分支和目录确认 Pages 服务设置的分支和部署目录与你推送代码的分支和目录结构一致。CDN 缓存Gitee Pages 可能使用了 CDN。CDN 节点有缓存时间。这是最常见的原因。解决等待通常等待 5-10 分钟CDN 缓存刷新后即可。强制刷新浏览器中按Ctrl F5或Cmd Shift R进行硬刷新。添加版本号为你引用的 CSS、JS 文件添加查询参数如style.css?v1.0.1这样浏览器和 CDN 会将其视为新资源。8.2 混合内容Mixed Content警告或阻塞现象网站部分功能失效浏览器控制台提示 “Mixed Content: The page at ‘https://...‘ was loaded over HTTPS, but requested an insecure resource ‘http://...‘”。原因你的网站通过 HTTPS 访问但 HTML 中某些资源图片、JS、CSS、字体的链接是 HTTP 协议。解决将资源链接的协议头http://改为https://。或者使用协议相对 URL即去掉协议头以//开头如//cdn.example.com/lib.js。这样浏览器会自动匹配当前页面的协议HTTP 或 HTTPS。8.3 GitHub Actions 同步失败现象GitHub Actions 工作流运行失败报错如 “Permission denied”, “Repository not found”。排查检查 Secrets确保GITEE_TOKEN和GITEE_USER在 GitHub Secrets 中设置正确没有多余的空格。检查令牌权限确认 Gitee 的私人令牌具有足够的权限至少包含projects的写权限。检查仓库名确保工作流 YAML 文件中的目标仓库地址${{ github.event.repository.name }}与 Gitee 上的仓库名完全一致大小写敏感。查看详细日志点击失败的 job查看具体的错误信息通常会有更明确的提示。8.4 自定义域名问题现象在 GitHub Pages 设置了自定义域名CNAME同步到 Gitee 后Gitee Pages 也想用同一个域名或者出现冲突。注意Gitee 的免费 Pages 服务不支持自定义域名绑定付费企业版可能支持。你只能使用gitee.io的子域名。建议如果你需要自定义域名并且主要面向国内用户可以考虑使用国内的云服务商如阿里云、腾讯云的对象存储配合 CDN 来托管静态网站成本很低。将 GitHub 作为源码库和自动化部署的触发源通过 Actions 自动构建并上传到对象存储。8.5 双平台配置差异管理核心矛盾GitHub Pages 和 Gitee Pages 可能需要不同的配置如base路径。最佳实践环境变量区分在构建命令中通过环境变量传递不同的base值。// package.json { “scripts”: { “build:github”: “vuepress build docs“, “build:gitee”: “BASE_URL’/my-repo/’ vuepress build docs“ } }多配置目录为两个平台分别准备构建输出目录如dist-github和dist-gitee在 GitHub Actions 中分别构建并部署到不同的远程分支或路径。忽略 Gitee 的配置文件在.gitignore中忽略 Gitee 特定的配置文件如_config.gitee.yml或者使用 Git 的sparse-checkout功能在同步时排除它们。整个流程走下来从最初的双平台配置到中间棘手的路径问题排查再到最后自动化工作流的搭建其实是一个典型的静态网站部署优化案例。关键在于理解不同平台服务之间的细微差异并运用构建工具和自动化流程来弥合这些差异。我个人的体会是前期在配置和自动化上多花一点时间后期维护的成本就会指数级下降。现在我的个人博客和项目文档都运行在这套双平台体系下GitHub 负责源码管理和国际访问Gitee 提供稳定的国内镜像两者通过 GitHub Actions 无缝同步再也不用为更新和访问问题头疼了。如果你也受困于类似的问题不妨从“配置基础路径”和“GitHub Actions 自动同步”这两个核心点入手相信能很快搭建起一套属于自己的高效发布流水线。
