Skip to content
Gitee Pages 部署静态网站
概述
Gitee Pages 是 Gitee 提供的静态网站托管服务。部署后站点可通过 https://<username>.gitee.io/<repo>/ 访问，支持自定义域名与 HTTPS。
该服务在部署流程与约束上和 GitHub Pages 有若干关键差异——主要集中在认证、自动触发与构建能力三方面。若这些限制与项目需求冲突，可以转为使用 Nginx 自建静态服务器。
部署流程
- 在 Gitee 新建仓库，可见性设为 公开（免费版强制要求）。
- 将静态文件（或本地构建产物）推送到仓库的部署分支。
- 进入仓库的「服务」→「Gitee Pages」页面，选择部署分支、指定部署目录（根目录或
/docs目录），然后开启服务。 - 服务开启后，站点即在对应的
gitee.io域名下可用。
部署目录的默认选项为根目录。若选择 /docs 目录，则 Pages 只会托管仓库中 docs/ 文件夹内的内容，其余文件不会被发布。
bash
# 示例：将 dist/ 下的构建产物推送到根目录部署
git checkout -b gh-pages
cp -r dist/* .
git add .
git commit -m "deploy"
git push origin gh-pages推送完成后站点不会自动刷新，必须在 Gitee Pages 设置页中点击“更新”按钮，新的内容才会对外生效。
与 GitHub Pages 的差异
| 维度 | GitHub Pages | Gitee Pages |
|---|---|---|
| 实名认证 | 不需要 | 需要（个人身份验证） |
| 仓库可见性 | 公开（免费版） | 公开（免费版） |
| 自动部署 | push 自动触发 | 手动触发（设置页点击“更新”） |
| 内置构建 | Jekyll / GitHub Actions | 不支持自动构建 |
| HTTPS | 自动（Let’s Encrypt） | 自动 |
| 自定义域名 | 支持 | 支持 |
实名认证
Gitee Pages 要求账号完成实名认证，需提供姓名与身份证号。这是启用服务的硬性前置条件，GitHub Pages 不存在这一步骤。
手动更新
推送到部署分支后，站点的线上内容不会自动更新。每次发布都需要登录 Gitee 进入 Pages 设置页手动触发“更新”。当更新频率较高时，这一步会固定成为人工操作节点。
无自动构建
Gitee Pages 仅托管静态文件，不参与构建过程。任何需要编译、打包的步骤都必须在本地或外部 CI 环境中完成，然后将构建产物（如 dist/）推送到仓库供 Pages 直接 serve。
Nginx 自建替代方案
当实名认证或手动更新流程与项目约束冲突时，可以用 Nginx 搭建静态服务器替代平台托管。
nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/app/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源长期缓存
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}try_files $uri $uri/ /index.html会按顺序尝试：请求的实际文件、请求路径对应的目录、最后回退到index.html。这对应单页应用（SPA）前端路由所需的后备机制。location /assets/对文件名带有哈希的静态资源设置长期缓存头，减少同一版本的重复网络请求。
部署链路如下：
本地或 CI 环境执行构建，生成
dist/。使用
rsync将产物同步到服务器。bashrsync -avz dist/ user@server:/var/www/app/dist/Nginx 直接 serve 新文件，无需额外手工干预。
HTTPS 可通过 Let’s Encrypt（certbot）自动获取与续期，配合 Nginx 启用加密访问。
自建方案的成本主体是一台轻量云服务器（约 50–100 元/月起步），收益是部署链路完全由自己控制，不再受平台认证、手动更新以及构建能力边界的限制。
注意点
- 仓库公开：Gitee Pages 免费版要求仓库为公开，这一点与 GitHub Pages 免费版一致。
- 手动更新：每次推送后务必在 Pages 设置页点击“更新”，否则线上内容不会变化。
- 部署目录：Pages 设置中可选的部署目录为根目录或
/docs，所选目录直接影响推送文件的组织方式。 - 子路径资源引用：若站点部署在
https://<username>.gitee.io/<repo>/子路径下，静态资源引用路径需做相应处理（如在 Vue CLI 中配置publicPath）。 - 带宽与请求限制：Gitee 未公开 Pages 服务的带宽上限，持续高流量的站点仍建议自建服务或使用 CDN。