1. 从一次“空白页面”的部署事故说起上周我正准备把一个刚写完的个人博客项目部署上线。按照惯例我同时推送到 GitHub 和 Gitee 的仓库想着两边都部署 Pages 服务一个给国外访客一个给国内用户加速访问完美。GitHub Pages 一如既往地顺利几分钟后页面就正常显示了。但当我打开 Gitee Pages 的链接时心凉了半截一个彻头彻尾的空白页面浏览器开发者工具的控制台里红彤彤的 404 错误扎眼地堆在那里所有的 CSS 样式文件和 JavaScript 脚本都加载失败。页面结构HTML是返回了但没了“衣服”CSS和“行为”JS自然就成了一具“骷髅”显示为一片空白。这其实不是一个新问题却是很多初次使用或从 GitHub 迁移到 Gitee Pages 的开发者必然会踩的坑。两者的服务虽然理念相似但在具体实现、尤其是路径处理和构建流程上存在一些关键差异。如果你也遇到了“Gitee Pages 访问界面为空白样式和JS文件404”的问题别慌这几乎是部署 Gitee Pages 的“成人礼”。今天我就结合自己的实测经验把 GitHub Pages 和 Gitee Pages 从配置、更新到解决这个经典404问题的完整流程掰开揉碎了讲清楚。无论你是用 VuePress、Hexo、Docsify 等静态站点生成器还是手写的 HTML/CSS/JS 项目这篇教程都能帮你一次跑通。2. GitHub Pages 与 Gitee Pages 的核心差异与配置起点在动手之前我们必须先理解这两个服务的不同“性格”这直接决定了后续的配置方式。GitHub Pages 出生在“云端”默认就为开源而生其构建服务器位于海外对各类现代前端工具链如 Jekyll、Hugo、VuePress的支持非常原生和自动化。而 Gitee Pages 诞生于国内环境最初更侧重于简单、直接的静态文件托管因此在自动化构建和路径解析上相对保守这也是导致404问题的根源之一。2.1 服务模式与构建触发GitHub Pages 提供两种主要模式1. 托管由 GitHub 自动构建的站点从特定分支如gh-pages或main分支的/docs文件夹2. 托管已经构建好的静态文件通常来自gh-pages分支。它的自动化程度很高当你推送代码到指定分支后GitHub Actions 或内置的 Jekyll 构建流程会自动启动生成站点文件。Gitee Pages 同样支持两种模式但逻辑略有不同1. 静态部署直接使用仓库里现有的文件通常是master或main分支2. 动态部署需要手动在服务端点击“更新”按钮Gitee 会拉取代码并在其服务器上执行你预设的构建命令如npm run build。关键在于Gitee 的“动态部署”并非实时监听推送而是一个手动触发的过程。许多人的空白页面问题就是因为没有正确使用或理解“动态部署”导致的。2.2 基础配置流程首次设置假设你已经有一个本地 Git 仓库里面是你的网站源码可能是生成器的源码也可能是构建好的dist或public文件夹。GitHub Pages 配置在 GitHub 上创建新仓库例如username.github.io(用户名替换为你的)这种命名方式仓库会直接启用 Pages。将本地仓库关联到远程git remote add origin https://github.com/username/username.github.io.git如果你用的是静态站点生成器通常需要将构建输出的目录如dist的内容推送到一个特定分支。以 VuePress 为例常用的是gh-pages分支。你可以使用gh-pages这个 npm 包自动化这个过程或者在 GitHub Actions 中配置工作流。推送代码后进入仓库的Settings - Pages。Source 选择部署的分支和文件夹例如gh-pages分支的/ (root)。稍等片刻即可通过https://username.github.io访问。Gitee Pages 配置在 Gitee 上创建新仓库名称自定。同样关联远程仓库git remote add gitee https://gitee.com/username/repo-name.git(注意远程仓库别名设为gitee以便区分)。首次部署你需要明确选择模式如果你推送的是已经构建好的静态文件直接推送到master分支。然后进入仓库的服务 - Gitee Pages。部署分支选择master部署目录填写/如果文件在根目录。点击“启动”。如果你推送的是源码需要 Gitee 帮你构建这就是“动态部署”。你需要在仓库根目录放置一个package.json文件其中包含构建命令如“build”: “vuepress build docs”。同样推送到master。然后在 Gitee Pages 设置页面选择“动态部署”并填写构建命令npm run build和输出目录dist根据你的项目而定。最后点击“启动”或“更新”。注意Gitee 的 Pages 服务对于免费用户每次更新都需要手动去页面点击“更新”按钮这是与 GitHub 最大的使用习惯差异也是很多人更新后看不到效果的原因。3. 详解“空白页面与404”问题的根因与解决方案现在进入核心故障环节。你的 Gitee Pages 页面打开了却是空白的F12 打开控制台看到类似https://gitee.com/username/repo-name/assets/style.css 404 (Not Found)的错误。问题出在资源路径上。3.1 问题根因相对路径与绝对路径的陷阱大多数静态站点生成器在构建时默认假设站点被部署在域名的根路径/下。因此它们生成的 HTML 中引用 CSS、JS、图片的路径通常是绝对路径以斜杠/开头例如/assets/style.css。这意味着浏览器会去站点的根域名下寻找这个资源即https://username.gitee.io/assets/style.css。然而Gitee Pages 的免费版有一个关键限制你的站点是部署在一个子路径下的其 URL 模式为https://username.gitee.io/repo-name/。注意末尾的repo-name/。当浏览器请求/assets/style.css时它实际请求的是https://username.gitee.io/assets/style.css而这个路径下根本没有你的仓库文件自然返回 404。你的站点文件实际在https://username.gitee.io/repo-name/assets/style.css。3.2 解决方案一修改静态站点生成器的“基础路径”Base Path这是最推荐、最一劳永逸的解决方案。你需要告诉你的构建工具站点将被部署在哪个子路径下。VuePress (v1.x / v2.x)在配置文件.vuepress/config.js或docs/.vuepress/config.js中设置base选项。module.exports { base: /repo-name/, // 你的 Gitee 仓库名 // ... 其他配置 }重新构建后所有资源路径都会自动加上/repo-name/前缀。VitePress在配置文件.vitepress/config.js中设置base选项。export default { base: /repo-name/, // ... }Hexo在站点配置文件_config.yml中修改url和root。url: https://username.gitee.io/repo-name root: /repo-name/注意url要写完整地址root以斜杠开头和结尾。Docsify在index.html中加载 docsify 的脚本前设置window.$docsify。script window.$docsify { basePath: /repo-name/, // ... } /script原生 HTML/CSS/JS 项目如果你是自己手写的项目没有用构建工具那么你需要手动将所有资源引用从绝对路径以/开头改为相对路径例如./assets/style.css或者使用相对于站点根目录的绝对路径但需要知道子路径。更规范的做法是也引入一个构建步骤如用 Vite 或 Webpack利用其publicPath配置来统一管理。3.3 解决方案二使用 Gitee 的“强制使用 HTTPS”和“自定义域名”间接解决如果你为 Gitee Pages 绑定了自定义域名例如blog.yourdomain.com并且域名解析正确那么你的站点就是部署在域名的根路径下了。此时绝对路径/assets/style.css指向的就是https://blog.yourdomain.com/assets/style.css路径问题自然消失。同时务必在 Gitee Pages 设置中开启“强制使用 HTTPS”避免混合内容警告。3.4 解决方案三针对已构建产物的手动修补临时方案如果你已经构建好了文件不想重新构建可以尝试一个临时方案进入构建输出目录如dist用文本编辑器全局搜索href/和src/将其替换为href./和src./。但这方法笨拙且容易出错仅适用于紧急情况或极简单的项目。4. 构建、更新与持续集成的自动化实践解决了路径问题我们还需要让更新流程更顺畅。手动点击 Gitee 的“更新”按钮太低效了。4.1 双仓库推送与手动更新最基本的流程是配置两个远程仓库一次推送两地更新。# 添加两个远程仓库 git remote add origin https://github.com/username/repo.git git remote add gitee https://gitee.com/username/repo.git # 推送代码 git push origin main # 推送到GitHub git push gitee main # 推送到Gitee推送完成后GitHub Pages 通常会自动更新。Gitee Pages 则需要你登录网页进入仓库的 Pages 服务页面手动点击“更新”按钮。虽然麻烦但步骤清晰。4.2 利用 Gitee 的 Webhook 与第三方服务实现自动更新进阶Gitee 免费版不支持像 GitHub Actions 那样的内置 CI/CD但我们可以借助 Webhook 和第三方自动化服务如 Jenkins、云函数或者利用 GitHub Actions 来触发 Gitee 的更新 API来模拟自动化。不过这些方案都需要额外的服务器或服务配置复杂度较高。一个相对简单的思路是在 Gitee 仓库设置中找到WebHooks添加一个 Hook。Payload URL 填写一个可以接收 POST 请求的端点例如一个你部署在云服务器上的简单脚本或者支持 Webhook 的自动化平台如 IFTTT、Zapier 的接口。这个端点在收到推送事件后调用 Gitee 的 Pages 构建 API。Gitee 提供了开放 API 用于触发 Pages 构建POST https://gitee.com/api/v5/repos/{owner}/{repo}/pages/builds。你需要先创建私人令牌在账号设置 - 安全设置 - 私人令牌来授权。编写一个脚本可以用 Python、Node.js 等当收到 Webhook 请求时验证签名可选然后使用你的私人令牌调用上述 Gitee API。4.3 使用 GitHub Actions 统一构建与同步推荐方案对于已经在使用 GitHub 的项目一个更优雅的方案是只在 GitHub 上维护源码利用 GitHub Actions 完成构建然后将构建好的静态文件同时部署到 GitHub Pages 和 Gitee Pages。这样你只需要向 GitHub 推送代码两边都能自动更新。具体步骤在 GitHub 仓库的 Settings - Secrets - Actions 里添加两个 SecretsGITEE_TOKEN你的 Gitee 私人令牌。GITEE_EMAIL你的 Gitee 账号邮箱。在 GitHub 仓库根目录创建.github/workflows/deploy.yml文件。编写 Action 工作流核心步骤包括检出代码拉取你的源码。安装依赖与构建执行npm install和npm run build生成静态文件到dist目录。部署到 GitHub Pages使用peaceiris/actions-gh-pages等 Action将dist目录推送到gh-pages分支。同步到 Gitee Pages这是一个关键步骤。你需要将构建好的dist目录内容推送到 Gitee 仓库的对应分支通常是pages分支。可以使用action来同步仓库或者直接配置 Git 推送到 Gitee。由于 Gitee 需要手动触发更新我们可以在推送完成后调用 Gitee 的 API 来触发 Pages 构建。以下是一个简化的 workflow 示例片段展示了构建和推送到 Gitee 仓库的思路name: Deploy to GitHub Gitee Pages on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install and Build run: | npm ci npm run build # 你的构建命令输出到 dist 目录 - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist - name: Deploy to Gitee Pages env: GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }} run: | cd ./dist git init git config user.name Your Name git config user.email ${{ secrets.GITEE_EMAIL }} git add . git commit -m Deploy to Gitee Pages via GitHub Actions # 强制推送到 Gitee 仓库的 pages 分支 git push --force --quiet https://$GITEE_TOKENgitee.com/your-username/your-repo.git master:pages # 可选调用 Gitee API 触发 Pages 构建 curl -X POST -H Content-Type: application/json -H Authorization: token $GITEE_TOKEN https://gitee.com/api/v5/repos/your-username/your-repo/pages/builds这个方案将自动化中心放在了 GitHub利用其强大的 Actions 生态间接实现了 Gitee Pages 的自动化更新是目前最实用的双平台部署方案。5. 实测中的其他常见坑点与排查清单即便按照上述步骤操作你可能还会遇到一些“幺蛾子”。这里是我总结的排查清单5.1 缓存问题浏览器和 Gitee 的 CDN 都可能存在缓存。当你更新了内容但页面没变时浏览器强制刷新CtrlF5 或 CmdShiftR。Gitee CDNGitee Pages 更新后生效可能有几分钟延迟。此外在 Gitee Pages 服务页面尝试点击“清除缓存”按钮如果有的话。5.2 构建命令或输出目录错误在 Gitee 的“动态部署”设置中“构建命令”和“发布目录”必须与你项目package.json中的脚本以及实际构建输出目录完全一致。例如你的package.json中“build”: “vuepress build docs”那么输出目录默认是docs/.vuepress/dist而不是根目录下的dist。填错了Gitee 就找不到构建好的文件部署的也就是个空目录。5.3 仓库公开性Gitee 的免费 Pages 服务通常要求仓库是公开的。如果你的仓库是私有的Pages 服务可能无法启用或访问。5.4 HTTPS 混合内容阻塞如果你的站点通过 HTTPS 访问但页面中引用的资源CSS、JS、图片却是 HTTP 协议现代浏览器会出于安全考虑阻止加载这些“混合内容”导致部分功能失效。确保所有资源链接都是 HTTPS或者在 Gitee Pages 设置中开启“强制 HTTPS”。5.5 单页应用SPA的路由问题如果你部署的是 Vue Router 或 React Router 管理的单页应用在 Gitee Pages 上直接访问非根路由如/about可能会得到 404。这是因为 Gitee Pages 服务器没有配置对所有路径都返回index.html。解决方法是在你的静态文件根目录放置一个404.html文件其内容就是index.html的拷贝。这样当服务器找不到路径对应的文件时会返回404.html从而加载你的 SPA 应用由前端路由接管。同时在前端路由中启用“哈希模式”Hash Mode也是一个简单的规避方案。5.6 检查构建产物最根本的在本地执行构建命令后务必打开生成的index.html文件检查里面的资源链接是否正确。例如是否已经正确加上了base如href“/repo-name/assets/style.css“。这是从源头杜绝问题的最好方法。整个流程走下来从配置、踩坑到解决和优化其实就是一个不断理解静态资源部署原理的过程。我的体会是永远不要假设不同平台的行为是一致的仔细阅读官方文档尽管可能不详细并用最笨的方法——检查构建产物的实际内容——来验证你的配置。把 GitHub Pages 当作生产环境的标准而把 Gitee Pages 视为需要特殊适配的国内镜像以这种心态去配置很多问题就迎刃而解了。最后拥抱自动化把重复的手动点击交给脚本你的效率会提升不止一个档次。