1. 项目概述：为什么选择Gitee Pages部署静态站点？
如果你是一名前端开发者、技术博主，或者只是想找个地方放一下自己的个人简历、项目展示页面，那么“部署一个静态站点”这个需求你一定不陌生。静态站点，说白了就是一堆HTML、CSS、JavaScript文件，不需要服务器端动态生成内容，访问速度快，维护简单。过去，我们可能会选择GitHub Pages，它确实方便，但对于国内用户来说，访问速度时快时慢，偶尔还会遇到“连接被重置”的尴尬，尤其是在需要给国内客户或团队成员快速预览的时候，这种不确定性就成了痛点。
这时，Gitee（码云）的Pages服务就进入了视野。作为国内领先的代码托管平台，Gitee Pages的服务器在国内，访问速度有天然优势，部署流程也足够简单，与GitHub Pages相似，降低了学习成本。这个项目的核心，就是利用Gitee Pages，将你的静态项目代码仓库，一键转化为一个可以通过公网域名访问的网站，实现快速、稳定的国内预览。无论是个人博客、项目文档、产品原型展示，还是小型企业官网，这都是一个高性价比的解决方案。接下来，我将以一个资深开发者的视角，带你从零开始，完整走一遍在Gitee上部署预览静态站点的全流程，并分享那些官方文档里不会写的实操细节和避坑指南。
2. 核心思路与前期准备：理清部署逻辑
在动手之前，我们必须先理解Gitee Pages的工作机制。它本质上是一个静态文件托管服务。你只需要在Gitee上创建一个仓库，将你的静态文件（比如index.html,style.css,main.js等）推送到这个仓库的特定分支（通常是master或main），然后在仓库设置中开启Pages服务。Gitee的后台程序会监听这个分支的更新，自动拉取代码，并将其发布到一个专属的域名下。
整个流程可以概括为：本地开发 -> 代码托管至Gitee仓库 -> 开启Gitee Pages服务 -> 自动生成访问链接。听起来很简单，但有几个关键决策点会直接影响后续的体验：
2.1 仓库类型选择：公开还是私有？
Gitee Pages服务对公开仓库是免费的。如果你部署的是开源项目文档、个人技术博客等希望被公开访问的内容，选择公开仓库即可。但如果你部署的是公司内部项目预览、给特定客户看的原型等需要保密的页面，就需要用到私有仓库。需要注意的是，Gitee的私有仓库开启Pages服务是需要付费的（属于Gitee企业版或会员权益）。在项目开始前，务必根据项目性质做出选择，避免中途变更带来麻烦。
2.2 项目结构规划：根目录还是docs目录？
Gitee Pages支持两种部署来源：
- 根目录：直接将仓库根目录下的文件作为网站根目录。
- Docs目录：将仓库根目录下的
/docs文件夹作为网站根目录。
如何选择？如果你的项目本身就是一个完整的静态网站项目，所有文件都放在项目根目录，那么选择“根目录”最直接。如果你的项目是一个包含文档的代码库（例如一个Vue/React项目，文档放在/docs目录下），那么选择“Docs目录”可以让你保持代码和文档在同一个仓库，又互不干扰。我个人的习惯是，纯静态展示站点用“根目录”，大型项目附带文档用“Docs目录”。
2.3 域名与自定义：默认域名够用吗？
开启Pages后，Gitee会提供一个默认的访问地址，格式是：https://你的用户名.gitee.io/仓库名。对于内部预览和测试，这个域名完全足够。如果你有自定义域名的需求（比如绑定自己的www.yourdomain.com），Gitee Pages也支持，但需要进行CNAME解析配置，这涉及到域名服务商的操作，步骤会稍复杂一些。对于初次部署，建议先使用默认域名跑通流程。
注意：Gitee Pages默认生成的HTTPS证书是针对其
gitee.io域名的。如果你绑定自定义域名且希望启用HTTPS，需要自行处理SSL证书（部分情况下Gitee可能会自动申请Let‘s Encrypt证书，但不保证），这是后期进阶时需要考虑的问题。
3. 实操全流程：从零部署一个示例站点
理论清晰后，我们进入实战环节。我将以一个最简单的个人简历页面为例，演示完整步骤。
3.1 第一步：本地项目准备
假设我们有一个最简单的项目结构，在本地创建一个文件夹，例如my-resume。
my-resume/ ├── index.html ├── style.css └── images/ └── avatar.jpgindex.html是入口文件，style.css是样式，images文件夹放图片。index.html内容可以非常基础：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>我的在线简历</title> <link rel="stylesheet" href="style.css"> </head> <body> <header> <img src="images/avatar.jpg" alt="头像" class="avatar"> <h1>张三 - 前端工程师</h1> <p>专注于构建优雅、高效的Web应用</p> </header> <section> <h2>项目经验</h2> <ul> <li>项目A：一个基于Vue的管理系统</li> <li>项目B：使用React Native开发的移动应用</li> </ul> </section> <footer> <p>© 2023 我的简历 | 通过Gitee Pages部署</p> </footer> </body> </html>style.css可以添加一些基本样式让页面看起来更舒服。这里的关键是，确保所有资源的引用路径是相对路径。比如href="style.css"和src="images/avatar.jpg"。绝对路径（如/style.css）或带协议头的路径（如https://example.com/style.css）在Pages环境下很可能无法正确加载。
3.2 第二步：在Gitee创建仓库并初始化
- 登录Gitee，点击右上角“+”号，选择“新建仓库”。
- 填写仓库信息：
- 仓库名称：例如
my-online-resume。这会成为你访问地址的一部分。 - 路径：会自动填充，一般与仓库名一致。
- 介绍：可选，填写“我的在线简历静态站点”。
- 仓库类型：根据之前分析，选择“公开”。
- 初始化设置：这里有一个重要选择。为了简化操作，我建议不要勾选“使用Readme文件初始化仓库”。因为如果你初始化了README，仓库就会立刻有一个
README.md文件在根目录。当你开启Pages服务并选择“根目录”部署时，这个README.md文件也会被部署到网站根目录。如果你的index.html文件名不是README.html，那么访问域名时，默认会列出文件列表而不是显示你的index.html页面，导致访问错误。对于纯静态站点，一个干净的初始状态更可控。 - 其他选项如.gitignore和开源许可证，可以根据需要选择，不影响Pages部署。
- 仓库名称：例如
- 点击“创建”。
仓库创建成功后，Gitee会给出如何将本地仓库关联并推送的指引。由于我们本地已有项目文件夹，采用“已有仓库”的方式。
3.3 第三步：关联本地项目与Gitee仓库
打开命令行终端（CMD、PowerShell或终端），进入你的my-resume项目目录。
# 初始化本地Git仓库 git init # 将本地文件添加到暂存区 git add . # 提交更改 git commit -m "初次提交：简历站点基础文件" # 将本地仓库与远程Gitee仓库关联 # 注意：将下面的URL替换成你刚创建的Gitee仓库的HTTPS或SSH地址 git remote add origin https://gitee.com/你的用户名/my-online-resume.git # 将本地代码推送到Gitee的master分支（现在主流是main，但Gitee默认创建master，按实际情况来） git push -u origin master执行git push后，需要输入你的Gitee账号密码。如果配置了SSH密钥，则无需密码。至此，你的代码已经安全地托管在Gitee上了。
3.4 第四步：开启Gitee Pages服务（最关键的一步）
- 进入你的Gitee仓库页面，点击上方导航栏的“服务”。
- 在左侧菜单中找到并点击“Gitee Pages”。
- 你会进入Pages部署页面。这里有几个选项：
- 部署分支：选择你推送代码的分支，通常是
master。 - 部署目录：选择“根目录”。（如果你把网站文件都放在
/docs里，就选“/docs目录”）。 - 强制使用HTTPS：建议勾选。这样你的站点会通过
https://协议访问，更安全。
- 部署分支：选择你推送代码的分支，通常是
- 点击“启动”或“更新”按钮。
启动后，Gitee会开始部署流程，页面会显示“正在部署”。这个过程通常需要1-3分钟。部署成功后，状态会变为“已开启”，并显示你的站点访问地址，例如：https://你的用户名.gitee.io/my-online-resume。
3.5 第五步：访问与验证
点击那个生成的链接，你的浏览器应该会成功打开你刚刚编写的简历页面。恭喜你，第一个通过Gitee Pages部署的静态站点已经上线了！
实操心得：第一次开启Pages后，如果访问页面出现404或者显示的是仓库文件列表而不是你的
index.html，别慌。首先检查部署目录是否选对。其次，刷新几次页面，或者等待几分钟，因为Gitee的CDN可能有缓存。最根本的，确保你的仓库根目录（或/docs目录）下确实存在名为index.html、index.htm或README.md的文件，因为Pages服务会优先寻找这些文件作为默认首页。
4. 进阶配置与自动化部署
基础流程走通后，我们可以追求更高效的 workflow。每次修改代码都要手动执行git add,git commit,git push三步，还是有些繁琐。对于使用现代前端框架（如Vue CLI、Create React App、Vite）生成的项目，我们还可以实现更自动化的部署。
4.1 使用脚本自动化推送
你可以在项目的package.json里添加一个deploy脚本。以Vue CLI项目为例，项目构建后生成的静态文件默认在dist目录下。我们需要将这个dist目录的内容推送到Gitee仓库的一个特定分支（比如gh-pages），或者直接推送到master分支的某个子目录（这需要调整部署目录为/dist，但Gitee Pages不支持直接部署子目录，所以更推荐用分支方式）。
一种常见的做法是，使用社区工具gh-pages（虽然名字叫gh-pages，但也可用于Gitee）。不过，对于Gitee，一个更直接的手动脚本思路是：
- 在Gitee仓库设置中，将Pages的“部署目录”设置为“根目录”。
- 本地项目构建后，将
dist目录下的所有文件复制到另一个专门用于部署的本地目录。 - 将这个部署目录初始化为一个Git仓库，并将其远程地址指向Gitee仓库。
- 每次构建后，清空部署目录，复制新的
dist文件进去，然后执行git add .,git commit,git push。
这个过程可以写成一个Shell脚本（deploy.sh）或Node.js脚本来自动执行。但请注意，这需要你妥善处理两个不同目录的Git历史，避免冲突。
4.2 利用Gitee的Webhook与CI/CD（高阶）
对于更复杂的项目，可以考虑使用Gitee Go（Gitee的CI/CD服务，类似Jenkins）或第三方CI工具（如Drone）。你可以配置一个流水线（Pipeline），当代码推送到master分支时，自动执行npm run build构建命令，然后将构建产物dist文件夹的内容同步到另一个专门用于Pages的仓库或分支，再触发该仓库的Pages更新。
不过，对于个人或小团队的大多数静态站点项目，手动推送或简单脚本已完全够用。引入CI/CD会带来额外的学习成本和配置复杂度，建议在项目确有频繁更新和自动化发布需求时再考虑。
5. 常见问题排查与避坑指南
在实际操作中，你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格，方便你快速查阅。
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 访问Pages地址显示404 | 1. 部署未成功或未完成。 2. 部署目录选择错误。 3. 根目录下没有 index.html等默认首页文件。4. 仓库是私有仓库但未开通付费服务。 | 1. 进入仓库“服务”->“Gitee Pages”，查看部署状态是否为“已开启”。 2. 确认“部署目录”设置是否正确（根目录 or /docs）。 3. 检查对应目录下是否存在 index.html。4. 公开仓库免费，私有仓库需付费升级。 |
| 页面能打开，但CSS/JS/图片不显示（样式错乱） | 资源文件引用路径错误。这是最高频的问题。 | 1. 检查浏览器开发者工具（F12）的“网络(Network)”标签，看哪些资源加载失败（状态码404）。 2. 确认HTML中引用资源的路径是相对路径，且相对于 index.html的位置正确。例如，如果CSS文件与HTML同级，用href="style.css"；如果在子目录css/下，用href="css/style.css"。3.特别注意：如果使用Vue Router的history模式，在非根路径部署时，需要配置 publicPath。 |
| 更新代码并推送后，网站内容没有变化 | Gitee Pages缓存。 | 1. Gitee Pages有缓存机制，通常几分钟内会更新。耐心等待。 2. 可以尝试在Pages服务页面点击“强制更新”或“重新部署”。 3. 清除浏览器缓存后再访问。 |
| 自定义域名绑定后无法访问或HTTPS证书错误 | DNS解析未生效或SSL证书问题。 | 1. 确认在域名服务商处设置的CNAME记录已生效（通常需要几分钟到几小时）。可用ping或nslookup命令检查。2. 在Gitee Pages设置中正确填写了自定义域名。 3. 如果提示HTTPS证书不安全，可能是证书未自动签发。可以尝试暂时关闭“强制HTTPS”，或联系Gitee客服咨询。 |
| 推送代码时被拒绝，提示无权限 | 远程仓库地址错误或未配置SSH密钥。 | 1. 检查git remote -v查看远程地址是否正确。2. 如果使用SSH方式，确认本地SSH公钥已添加到Gitee账户设置中。 3. 如果使用HTTPS方式，可能是密码错误。Gitee现已要求使用个人令牌代替密码进行HTTPS操作。需在Gitee设置中生成令牌，并用令牌作为密码。 |
| 开启Pages时，提示“仓库容量超过1G”或“文件数量过多” | Gitee Pages对仓库大小和文件数量有限制。 | 1. 静态站点通常不会这么大，检查是否误提交了node_modules、.git、大型媒体文件等。2. 使用 .gitignore文件忽略不需要的文件。3. 优化图片等资源，使用CDN托管大型文件。 |
5.1 关于“你尝试预览的文件可能对你的计算机有害”的提示
这个提示有时会在Windows系统本地直接双击打开HTML文件时，被Windows Defender SmartScreen或浏览器拦截。这与Gitee Pages无关，是本地系统的安全策略。它认为从网络（或本地不确定来源）下载的文件有潜在风险。解决方案是：
- 在本地服务器环境预览（如用VSCode的Live Server插件）。
- 信任该文件（如果确认安全），在浏览器提示时选择“保留”或“仍然打开”。
- 部署到Gitee Pages后，通过
https://链接访问，则完全不会出现此提示。
5.2 部署包含前端路由（History模式）的项目
如果你用Vue Router或React Router且使用了history模式（即去掉URL中的#），在Gitee Pages上直接访问非首页路由（如https://xxx.gitee.io/about）会返回404。这是因为Gitee的服务器没有配置对所有路径都返回index.html。
解决方案：在你的静态项目根目录下，添加一个名为404.html的文件。其内容就是你的index.html文件的完整拷贝。当Gitee服务器找不到对应路径的资源时，会回退到404.html，而这个文件加载了你的前端应用，前端路由就能正常接管并显示对应页面了。这是一个非常实用且通用的技巧。
6. 性能优化与最佳实践
站点部署成功只是第一步，要让访问体验更好，还需要一些优化。
6.1 启用HTTPS
务必在Gitee Pages设置中勾选“强制使用HTTPS”。这不仅安全，也是现代浏览器的推荐做法，某些新的Web API（如地理位置）在非HTTPS环境下甚至无法使用。
6.2 利用浏览器缓存
对于不常变化的静态资源（如图片、字体、打包后的CSS/JS文件），可以通过在文件名中加入哈希值（例如style.a1b2c3d4.css）来实现“缓存破坏”。当文件内容变化时，文件名哈希值改变，浏览器会视为新文件重新加载；未变化时，则直接使用本地缓存。现代前端构建工具（如Webpack、Vite）在生产模式构建时会自动完成这项工作。
6.3 图片等静态资源优化
巨大的图片是拖慢网站加载速度的元凶。在上传前，务必使用工具（如TinyPNG、Squoosh）对图片进行压缩。对于站点Logo、图标等，优先使用SVG格式，它体积小且缩放无损。
6.4 考虑使用CDN加速第三方库
如果你的页面引用了jQuery、Bootstrap、Vue等第三方库，不要直接下载到自己的项目里引用。而是使用这些库提供的公共CDN链接（如unpkg、cdnjs）。这样可以利用用户浏览器可能已有的缓存，加快加载速度。
例如，替换本地的Vue.js引用：
<!-- 本地引用 --> <script src="./js/vue.js"></script> <!-- 改为CDN引用 --> <script src="https://cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>6.5 保持仓库整洁
定期检查仓库，使用.gitignore文件忽略构建产物（如dist/、build/）、依赖目录（node_modules/）、编辑器配置文件（.vscode/、.idea/）等。只将源代码和必要的配置文件提交到仓库。这能让仓库更小，Pages部署和拉取速度也可能更快。
部署静态站点到Gitee Pages是一个将想法快速呈现给国内观众的高效途径。整个过程的核心在于理解“静态托管”的概念，掌握Git的基本操作，并细心处理文件路径问题。当你熟悉了这个流程后，你会发现它就像搭积木一样简单可靠。无论是用于临时演示、长期文档，还是个人品牌展示，它都是一个值得放入工具箱的稳定选择。
