Gitee Pages部署后页面空白怎么办？

Question

Gitee Pages部署后页面空白怎么办？一个常见原因是静态资源路径配置错误。当项目使用相对路径引用CSS、JS或图片文件时，若未正确设置公共路径（publicPath），Gitee Pages在访问子路由或非根目录部署时可能无法加载资源，导致页面空白。建议检查构建工具（如Vue CLI或Vite）的配置文件，将`publicPath`设为项目仓库名对应的路径（如`/your-repo-name/`），并确保index.html中资源引用正确。构建后本地预览dist目录内容，确认无404错误后再推送部署。

Answer 1

一、Gitee Pages部署后页面空白：从现象到本质的深度剖析

在前端工程化实践中，Gitee Pages已成为静态站点托管的常用选择。然而，开发者常遇到“部署后页面空白”的问题。表面看是UI未渲染，实则多为静态资源（CSS、JS、图片等）加载失败所致。本文将围绕静态资源路径配置错误这一核心原因，结合构建工具配置、部署环境差异和调试策略，系统性地展开分析。

1.1 现象描述与初步排查

• 访问Gitee Pages生成的URL时，浏览器显示空白页面
• 打开开发者工具（F12），发现Network面板中大量404错误
• 请求的JS/CSS文件路径指向根目录（如/js/chunk-vendors.js），但实际资源位于/your-repo-name/js/...
• HTML文件成功返回，但控制台报错“Uncaught ReferenceError”或“Failed to load module”

1.2 根本原因：publicPath 配置不当

现代前端框架（如Vue、React）通过构建工具（Webpack、Vite）打包资源。若未正确设置publicPath，生成的资源引用路径将默认相对于根目录（"/"），而Gitee Pages的项目通常部署在子路径下（如https://username.gitee.io/repo-name/）。此时浏览器尝试从https://username.gitee.io/js/app.js加载资源，而非正确的https://username.gitee.io/repo-name/js/app.js，导致404。

1.3 构建工具层面的解决方案

根据使用的构建工具，需调整相应配置：

1.3.1 Vue CLI 项目（vue.config.js）

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/your-repo-name/'  // 替换为你的Gitee仓库名
    : '/'
}

1.3.2 Vite 项目（vite.config.js）

export default defineConfig({
  base: '/your-repo-name/', // 注意结尾斜杠
})

1.3.3 React + CRA（需 eject 或使用 craco）

配置项	值	说明
homepage	"https://username.gitee.io/your-repo-name"	package.json 中添加 homepage 字段
publicPath	自动推导	CRA 会基于 homepage 自动生成 publicPath

1.4 部署前验证流程

为避免重复试错，建议在本地模拟部署环境进行预览：

1. 执行构建命令：npm run build
2. 进入 dist 目录：cd dist
3. 启动本地HTTP服务器：npx serve -s 或 python -m http.server 8080
4. 访问 http://localhost:8080/your-repo-name/ 模拟子路径部署
5. 检查浏览器控制台是否有404或加载错误
6. 确认无误后再推送至Gitee

1.5 进阶调试：动态publicPath与CDN适配

在复杂场景中，可能需要运行时动态判断publicPath。例如，同一构建产物用于多个环境（开发、测试、Gitee Pages）：

// webpack.config.js 动态设置
__webpack_public_path__ = window.location.pathname.startsWith('/your-repo-name/')
  ? '/your-repo-name/'
  : '/';

1.6 流程图：Gitee Pages 资源加载失败诊断路径

graph TD
            A[页面空白] --> B{查看Network面板}
            B --> C[是否存在404]
            C -->|是| D[检查资源请求路径]
            D --> E[是否缺少 /repo-name/ 前缀]
            E -->|是| F[修改 publicPath/base 配置]
            F --> G[重新构建并本地预览]
            G --> H[推送至Gitee]
            H --> I[验证部署结果]
            C -->|否| J[检查JavaScript运行时错误]
            J --> K[分析控制台异常堆栈]

1.7 其他潜在因素补充

除路径问题外，还需排除以下可能性：

• index.html 编码问题：确保文件编码为UTF-8，避免BOM头干扰
• 路由模式冲突：使用Vue Router history模式时，需配置Gitee Pages重定向规则
• 缓存问题：强制刷新（Ctrl+F5）或清除PWA缓存
• 跨域限制：若引用外部API，检查CORS策略
• GitHub/Gitee Pages 差异：Gitee不支持自定义404.html重定向，需注意SPA兼容性

1.8 自动化部署脚本示例

结合CI/CD，可在.gitee/CI.yml中集成构建与路径校验：

pages:
  stage: deploy
  script:
    - npm install
    - export REPO_NAME=$(basename $(pwd))
    - sed -i "s|publicPath:.*|publicPath: '/\$REPO_NAME/'|" vue.config.js
    - npm run build
    - cd dist && python -m http.server 8080 &
    - sleep 5
    - curl -f http://localhost:8080/\$REPO_NAME/index.html || exit 1
  artifacts:
    paths:
      - dist
  only:
    - main