1. 为什么我们需要一个国内的静态站点预览环境如果你是一个在国内工作的开发者或者你的项目主要面向国内用户那么你一定遇到过这样的场景辛辛苦苦写好的前端页面用npm run build生成了一堆html、css、js文件然后你需要一个地方来展示它。你可能会想到 GitHub Pages但它的访问速度在国内时好时坏尤其是在没有特殊网络环境的情况下加载一个简单的页面都可能转圈圈十几秒。更别提有时候你需要给产品经理、设计师或者客户快速预览一个效果对方却因为网络问题根本打不开沟通成本瞬间拉满。这时候一个稳定、快速、且在国内访问无障碍的静态站点托管服务就显得尤为重要。Gitee Pages作为国内代码托管平台 Gitee码云提供的静态页面托管服务就成了很多开发者的首选。它不仅仅是一个“能访问”的替代品更因其与国内开发流程的无缝集成成为了团队协作、项目演示、个人博客搭建的利器。我经历过多次在紧急联调时因为预览环境卡顿而耽误进度的窘境最终将项目的预览部署全部迁移到了 Gitee Pages体验提升立竿见影。2. 前期准备从零开始搞定 Gitee 仓库在开始部署之前我们需要做好两件事拥有一个 Gitee 账号以及准备好你的静态站点项目代码。这听起来简单但细节决定成败。2.1 注册与创建仓库首先访问 Gitee 官网并注册账号这个过程和大多数网站类似不再赘述。重点是创建仓库。登录后点击右上角的 “” 号选择 “新建仓库”。这里有几个关键选项需要仔细填写仓库名称建议使用英文例如my-static-site。这个名字会直接影响你后续的访问地址。路径通常会自动填充为仓库名称保持默认即可。仓库介绍简单描述项目方便自己和管理员理解。是否开源根据项目性质选择。对于纯粹用于预览的静态站点选择“公开”通常没问题。如果涉及敏感信息请选择“私有”但请注意Gitee Pages 服务对私有仓库可能有功能或访问限制需查阅最新官方文档。初始化仓库这里有一个至关重要的选择。我强烈建议你不要勾选“使用 Readme 文件初始化这个仓库”。为什么因为如果你勾选了仓库会立即创建一个master分支和一个README.md文件。而 Gitee Pages 默认从master分支部署。这意味着你之后需要将本地项目代码强制推送到这个已初始化的远程仓库操作会稍微复杂一点需要git push -f。对于新手最稳妥的方式是从一个空白仓库开始。所以最省事的做法是只填写仓库名称其他保持默认不初始化直接点击“创建”。2.2 本地项目初始化与 Git 配置假设你的静态站点项目已经开发完成并且位于本地目录my-project下。这个目录下应该有index.html以及相关的资源文件。打开终端或命令行进入你的项目目录cd /path/to/your/my-project接下来我们需要将这个目录初始化为一个 Git 仓库并将其与刚刚在 Gitee 上创建的空白仓库关联起来。首先初始化本地仓库git init然后将当前目录下的所有文件除了.gitignore中声明的添加到暂存区。建议先创建一个.gitignore文件忽略node_modules等依赖目录。# 添加所有文件到暂存区 git add . # 或者更精确地添加 # git add index.html css/ js/ images/提交你的更改这是项目的第一次提交git commit -m Initial commit: static site source code现在需要关联远程仓库。回到 Gitee 你刚创建的仓库页面找到“克隆/下载”区域复制 HTTPS 链接格式如https://gitee.com/your-username/your-repo-name.git。在终端中添加这个远程仓库地址git remote add origin https://gitee.com/your-username/your-repo-name.git这里origin是给这个远程地址起的一个别名通用且方便。最后将本地代码推送到远程仓库。由于远程仓库是空的我们使用-u参数将本地的master分支与远程的master分支关联起来并首次推送git push -u origin master输入你的 Gitee 账号密码或配置了 SSH 密钥则无需密码后代码就成功推送到了 Gitee。刷新你的仓库页面应该能看到项目文件了。注意如果你在创建仓库时不小心初始化了 README那么远程仓库会先有一个提交。此时直接push会失败因为历史不一致。你需要先执行git pull origin master --allow-unrelated-histories来合并两个不相关的历史解决可能出现的冲突后再push。这就是为什么一开始建议创建空仓库的原因。3. 核心操作开启并配置 Gitee Pages 服务代码上传只是第一步让这些静态文件变成一个可以通过网址访问的网站才是关键。这就是 Gitee Pages 的功能。3.1 在仓库中启用 Gitee Pages进入你的 Gitee 仓库页面在导航栏中找到 “服务” 菜单在下拉选项中选择 “Gitee Pages”。你会进入 Pages 服务的部署页面。如果你是第一次使用页面可能会提示你需要进行实名认证。根据国内相关规定Gitee Pages 服务要求用户完成实名认证后才能使用。按照指引完成认证即可过程通常很快。认证完成后回到部署页面你会看到主要的配置选项部署分支默认是master分支。这意味着 Gitee Pages 会使用你master分支根目录下的文件来构建网站。如果你的构建产物如dist,build目录不在根目录或者你希望用其他分支如gh-pages来部署可以在这里修改。对于简单项目保持master即可。部署目录默认是/即分支的根目录。如果你的网站文件在一个子目录里比如你的构建工具将文件输出到了dist文件夹那么这里就需要填写/dist。这是最容易出错的地方之一。很多新手直接将 Vue/React 项目的源码推上去然后部署目录填/结果访问页面一片空白因为根目录下是package.json而不是index.html。务必确认你的index.html在部署目录下。强制使用 HTTPS建议勾选。启用后你的站点将通过https://协议访问更加安全。自定义域名可选如果你有自己的域名可以在这里绑定。需要先在域名服务商那里添加一条 CNAME 记录指向 Gitee 提供的域名如your-username.gitee.io。这对于打造品牌或个人博客非常有用。配置完成后点击 “启动” 或 “更新” 按钮。Gitee 会开始部署流程。3.2 理解部署过程与访问地址点击启动后页面会显示“正在部署”的状态。部署通常需要1-2分钟。完成后状态会变为“已启动”并显示你的站点访问地址。你的站点地址格式通常是https://your-username.gitee.io/your-repo-name/例如用户名为zhangsan仓库名为my-demo那么访问地址就是https://zhangsan.gitee.io/my-demo/。这里有一个非常重要的细节Gitee Pages 默认是项目站点其访问路径包含了仓库名。这与 GitHub Pages 的username.github.io这种用户/组织站点不同。这意味着你在代码中引用资源如图片、CSS、JS时如果使用绝对路径可能需要考虑这个基础路径。例如你的index.html中有一张图片img src/images/logo.png在本地可能正常但在 Gitee Pages 上它实际上会去访问https://zhangsan.gitee.io/images/logo.png这显然是 404。正确的引用应该是img src./images/logo.png相对路径或者img src/my-demo/images/logo.png包含仓库名的绝对路径。对于使用 Vue CLI、Create React App 等现代前端脚手架构建的项目它们通常能很好地处理公共路径publicPath你只需要在构建配置中将其设置为/your-repo-name/即可。部署成功后你可以立即点击提供的链接访问你的网站。第一次访问可能会有一点延迟属于正常现象。4. 高级工作流自动化部署与持续集成每次修改代码后都需要手动执行git push然后手动到 Gitee 页面点击“更新”部署吗对于追求效率的开发者来说这太繁琐了。我们可以利用 Gitee 的 WebHook 或第三方 CI/CD 工具实现自动化。4.1 基于 Gitee WebHook 的自动更新Gitee Pages 服务本身提供了一个“自动更新”的选项。在 Pages 部署页面勾选“当仓库有更新时自动重新部署”。这样每次你向部署分支如master推送代码时Gitee 会自动触发一次 Pages 部署无需手动点击。这已经解决了大部分自动化需求。但它的局限性在于它只在你推送代码到特定分支后触发部署。如果你的项目需要先进行构建例如需要运行npm run build将 Vue/React 源码转换为静态文件那么你推送到仓库的应该是构建后的dist目录内容而不是源码。这就引出了更高级的用法将构建过程也自动化。4.2. 集成 CI/CD 实现“推送源码自动构建并部署”理想的工作流是你在本地开发完成后将源代码推送到master分支的某个目录例如/src。然后一个自动化的流程被触发这个流程在云端执行npm install和npm run build再将生成的dist目录内容推送到另一个专门用于部署的分支例如pages最后触发 Gitee Pages 从pages分支部署。Gitee 提供了自己的 CI/CD 服务叫 Gitee Go原名 Gitee CI。你可以通过在仓库根目录创建一个.gitee/.workflow目录下的 YAML 配置文件来实现。下面是一个简化示例的步骤思路创建 workflow 文件在仓库中创建.gitee/.workflow/pages-pipeline.yml。编写 pipeline 逻辑定义当代码推送到master分支时触发一个构建任务。这个任务在一个干净的容器环境中拉取你的代码安装 Node.js 依赖执行构建命令。处理构建产物构建成功后任务需要将dist目录的内容提取出来。由于 Gitee Go 的任务环境是临时的我们需要将产物“推送”到某个地方。一个常见做法是利用 Git 命令将dist目录的内容强制推送到仓库的pages分支。配置 Pages将 Gitee Pages 的部署分支设置为pages并开启自动更新。这样整个流程就闭环了git push源码 - CI 自动构建 - CI 将构建结果推送到部署分支 - Pages 自动更新站点。由于 Gitee Go 的配置细节较多且界面和功能可能更新这里不展开具体 YAML 语法。但核心思想就是利用自动化脚本将“构建”和“部署”这两个动作从本地迁移到云端保证部署环境的纯净和一致性也解放了开发者的双手。实操心得对于个人或小团队项目直接推送构建后的dist目录到master分支并开启 Gitee Pages 的自动更新是最简单直接的方案维护成本最低。只有当你需要严格区分源码和产物或者有复杂的多环境构建需求时才值得去搭建完整的 CI/CD 流水线。5. 常见问题排查与性能优化即使按照步骤操作你也可能会遇到一些问题。下面是我在多次部署中总结的一些常见坑点及其解决方案。5.1 页面访问 404 或空白这是最常见的问题。原因一部署目录错误。检查你的 Gitee Pages 设置中的“部署目录”。如果项目根目录没有index.html而你的index.html在dist文件夹里那么部署目录就应该是/dist。原因二资源引用路径错误。打开浏览器的开发者工具F12查看“网络”Network标签页。看看是否有 CSS、JS、图片等资源加载失败状态码为 404。这通常是因为在 HTML 中使用了错误的路径。对于单页应用SPA确保你的路由模式是hash模式例如http://site.com/#/home因为 Gitee Pages 是静态托管不支持history模式如http://site.com/home的服务器端路由回退。如果非要用history模式需要配置 Gitee Pages 将所有请求重定向到index.html部分托管服务支持需确认。原因三缓存。Gitee Pages 可能有 CDN 缓存。即使你更新了代码并成功部署访问到的可能还是旧页面。尝试强制刷新浏览器CtrlF5或者清除浏览器缓存。也可以在页面 URL 后添加一个无用的查询参数来绕过缓存如?v1。5.2 自定义域名绑定失败绑定自定义域名后无法访问通常是因为 DNS 解析未生效或配置错误。检查 CNAME 记录在你的域名管理后台确保已添加一条 CNAME 记录将你的域名如demo.yourdomain.com指向your-username.gitee.io。记录类型是CNAME主机记录是demo如果你要用子域名或如果用根域名记录值就是your-username.gitee.io。等待 DNS 生效DNS 变更全球生效可能需要几分钟到几小时。你可以使用nslookup或dig命令来检查解析是否已指向 Gitee。检查 Gitee 配置在 Gitee Pages 设置中正确填写了带协议http://或https://的完整域名。HTTPS 证书Gitee 会为绑定的自定义域名自动申请 Let‘s Encrypt 的 SSL 证书但这可能需要一些时间。在证书签发前通过 HTTPS 访问可能会报错。可以稍等一段时间再试。5.3 网站加载速度优化虽然 Gitee Pages 在国内访问已经很快但我们还可以让它更快。开启 Gitee Pages 的强制 HTTPS这不仅安全而且 HTTP/2 协议在 HTTPS 下才能发挥最佳性能支持多路复用加快资源加载。优化静态资源压缩确保你的 HTML、CSS、JS 文件都经过了压缩minify。使用 Webpack、Vite 等构建工具可以轻松完成。图片优化使用现代格式如 WebP并对 PNG/JPG 进行无损或有损压缩。工具如imagemin可以集成到构建流程中。代码分割与懒加载对于大型单页应用利用构建工具将代码拆分成多个块chunk并按需加载减少首屏资源体积。利用浏览器缓存通过配置 HTTP 响应头如Cache-Control让浏览器缓存静态资源如图片、CSS、JS。Gitee Pages 本身对静态资源有缓存策略但我们可以在文件名中加入哈希值例如app.abc123.js来实现“永久缓存”当文件内容变化时文件名哈希值改变相当于新的 URL从而绕过缓存。5.4 项目更新后页面未变化你推送了代码Gitee Pages 也显示部署成功但访问网站还是旧内容。确认部署分支你是否推送到了正确的分支比如 Pages 设置的是master分支但你推送到了develop分支。检查构建流程如果你的项目需要构建确认你推送的是构建后的文件还是源代码如果是源代码需要确认自动构建流程是否成功执行。清除 CDN 缓存Gitee Pages 背后有 CDN。你可以尝试在 Gitee Pages 部署页面先点击“停止”等待几秒后再点击“启动”强制 CDN 刷新。但这并非百分百有效最可靠的方法是等待缓存自然过期通常时间不长。部署静态站点到 Gitee Pages 是一个简单但极其实用的技能它完美解决了国内开发者对快速、稳定预览环境的刚需。从最基础的手动上传到配置自动化流水线整个过程体现了现代前端工程化的基本思想。关键在于理解“静态托管”的本质服务器只是简单地返回文件所有路由和逻辑都在前端处理。把握住这一点再结合 Gitee 平台提供的具体配置选项就能轻松驾驭。我个人最大的体会是将预览环境固定下来并自动化后团队沟通效率得到了质的提升再也不用为“你那边能看到最新效果吗”这样的问题而反复确认了。