零成本部署个人项目：GitLab Pages静态托管实战指南

菩提流支

1. 为什么选择GitLab Pages托管静态网站？

作为一个经常折腾个人项目的开发者，我深知展示作品的重要性。以前每次想分享自己的技术博客或者作品集，总要纠结服务器的问题——要么花钱买云服务，要么用国内各种需要备案的平台，过程繁琐不说，成本还高。直到发现了GitLab Pages这个神器，我的个人项目展示问题才真正得到解决。

GitLab Pages本质上是一个静态网站托管服务，它允许你直接从GitLab仓库发布网站内容。和需要服务器动态渲染的传统网站不同，静态网站由纯HTML、CSS和JavaScript文件组成，访问时直接返回这些预先生成的文件，不需要额外的服务器处理。这种架构特别适合个人博客、作品集、项目文档和小型演示页面。

我选择GitLab Pages而不是其他类似服务（比如GitHub Pages）有几个关键原因：首先，它提供完全免费的CI/CD流水线，每次代码提交都会自动构建和部署；其次，支持自定义域名和HTTPS证书，而且是免费的；最后，构建限制相对宽松，对于个人项目来说完全够用。实测下来，我的技术博客已经稳定运行了两年多，从没出过问题。

2. 从零开始搭建你的第一个GitLab Pages项目

2.1 准备工作与环境配置

在开始之前，你需要准备三样东西：一个GitLab账号（如果没有就去官网注册）、本地Git环境（建议安装最新版Git）和一个文本编辑器（VS Code就不错）。我建议直接在GitLab.com上操作，因为自建GitLab实例可能需要额外配置。

注册完成后，点击"New project"创建新项目。这里有个小技巧：如果你想创建个人主页，可以把项目命名为[你的用户名].gitlab.io，这样完成后就能直接用这个地址访问。比如我的用户名是dev-zhang，项目名就是dev-zhang.gitlab.io。这种命名方式会让你的网站自动成为GitLab Pages的根站点。

创建好项目后，在本地找个合适的位置，用Git克隆这个空仓库：

bash复制git clone https://gitlab.com/你的用户名/你的项目名.git
cd 你的项目名

2.2 创建基础网站结构

进入项目目录后，我们可以开始构建网站内容了。最简单的静态网站只需要一个index.html文件。用你喜欢的编辑器创建一个，内容可以像这样：

html复制<!DOCTYPE html>
<html>
<head>
    <title>我的个人网站</title>
    <style>
        body { font-family: Arial; max-width: 800px; margin: 0 auto; }
    </style>
</head>
<body>
    <h1>欢迎来到我的GitLab Pages网站</h1>
    <p>这是我的第一个静态网站，托管在GitLab Pages上！</p>
</body>
</html>

如果你想用静态网站生成器（比如Hugo或Jekyll），现在也是初始化项目的好时机。以Hugo为例：

bash复制hugo new site . --force
hugo new posts/first-post.md

3. 配置CI/CD实现自动部署

3.1 编写.gitlab-ci.yml文件

GitLab Pages的核心魔法在于它的CI/CD系统。我们需要在项目根目录创建一个名为.gitlab-ci.yml的文件，告诉GitLab如何构建和部署我们的网站。

对于纯HTML项目，配置非常简单：

yaml复制pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r ./* .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

如果你使用静态网站生成器，配置会稍有不同。以Hugo为例：

yaml复制image: registry.gitlab.com/pages/hugo:latest

pages:
  stage: deploy
  script:
    - hugo
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

3.2 提交并触发首次部署

文件准备好后，提交到GitLab：

bash复制git add .
git commit -m "Initial commit with basic setup"
git push origin main

推送完成后，打开GitLab项目页面，进入CI/CD > Pipelines，你会看到一个新的流水线正在运行。点击进入可以查看实时日志。通常第一次构建会花费1-2分钟。

构建成功后，你的网站就可以通过https://[你的用户名].gitlab.io/[项目名]访问了。如果是按照[用户名].gitlab.io命名的项目，直接访问https://[你的用户名].gitlab.io即可。

4. 高级配置与自定义域名设置

4.1 添加自定义域名

虽然GitLab提供的子域名已经很好用了，但如果你想使用自己的域名（比如zhang.dev），配置起来也很简单。首先，在域名注册商那里添加一条CNAME记录，指向[你的用户名].gitlab.io。

然后在GitLab项目设置中，进入Pages > New Domain，输入你的域名并勾选"Auto redirect to this domain"。GitLab会自动为你申请Let's Encrypt SSL证书，通常几分钟内就能生效。

4.2 优化构建速度

随着项目变大，你可能会发现构建时间变长。这里有几个优化技巧：

使用.gitlab-ci.yml中的cache功能缓存依赖：

yaml复制cache:
  paths:
    - public
    - resources/_gen

yaml复制script:
  - hugo --minify --gc --cleanDestinationDir

使用更轻量的基础镜像，比如alpine版本

4.3 多环境部署

有时候你可能需要区分开发环境和生产环境。可以通过不同的Git分支来实现：

yaml复制stages:
  - build
  - deploy

build:
  stage: build
  script:
    - hugo -D -F -b $DEPLOY_URL
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

pages:
  stage: deploy
  dependencies:
    - build
  script:
    - rm -rf public
    - mv build/public .
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

5. 常见问题排查与解决方案

在实际使用中，我遇到过几个典型问题。首先是构建失败，最常见的原因是.gitlab-ci.yml文件格式错误或者静态网站生成器版本不兼容。建议先在本地测试构建过程，确保没问题再提交。

另一个常见问题是自定义域名设置后无法访问。这时候要检查几点：DNS解析是否生效（可以用dig命令检查）、GitLab的域名验证是否通过、SSL证书是否成功签发。有时候需要等待24小时让所有变更完全生效。

缓存问题也经常让人头疼。如果发现更新后的内容没有显示，尝试在CI/CD设置中清除Runner缓存，或者在.gitlab-ci.yml中禁用缓存测试。

最后是资源限制问题。GitLab Pages有每月100GB的流量限制和10GB的存储限制，对于个人项目来说完全够用。但如果你的网站有大量媒体文件，建议使用CDN或者对象存储服务来分担压力。

已经到底了哦

精选内容

1 STM32 HAL 微秒延时指令方案的实战调优与精度校准 2 Linux内核内存管理：手把手带你读懂进程的虚拟地址地图（vm_area_struct详解）3 深入剖析SM4算法：从原理到C++高效实现 4 FedAvg之外：聊聊联邦学习落地时，那些比算法更头疼的工程挑战 5 别再被MIG核的DDR3仿真卡住了！手把手教你从IP例程里找到并添加仿真模型文件 6 合宙Air780EG串口调试避坑指南：从硬件焊接到LuatOS代码，手把手教你搞定uart收发 7 LVGL Tableview控件实战：5分钟搞定嵌入式GUI的选项卡切换（附完整代码）8 PDFbox进阶：坐标定位与分页读取实战指南 9 ESP32 LVGL实战：lv_font_conv工具进阶指南——自定义字体与图标库的构建与优化 10 从基础到进阶：深度解析MATLAB矩阵运算中元素级与矩阵级运算符的核心差异与应用场景