Silencejql
0%

Hexo部署到Gitlab

发表于 Valine：
本文字数： 4.1k 阅读时长 ≈ 4 分钟

博客部署到Gitlab与部署到Github等生成静态页面不同, Gitlab中需要存储完整代码.

完整步骤

以下是使用 Hexo 部署到 GitLab Pages 创建个人博客的完整指南，包含详细步骤和常见问题排查：

一、准备工作

  1. 安装 Node.js 和 npm
    Hexo 基于 Node.js，需先安装 Node.js（建议选择 LTS 版本）。

  2. 安装 Git
    下载并安装 Git，用于代码管理。

  3. 注册 GitLab 账号
    访问 GitLab 注册账号。

二、安装 Hexo 并初始化博客

  1. 全局安装 Hexo 命令行工具

    1
    npm install -g hexo-cli

  2. 创建 Hexo 项目

    1
    2
    3
    hexo init my-blog  # 创建名为 my-blog 的博客目录
    cd my-blog         # 进入项目目录
    npm install        # 安装依赖

  3. 本地预览

    1
    hexo server        # 启动本地服务器

    访问 http://localhost:4000 查看默认博客。

三、关联 GitLab 仓库

  1. 在 GitLab 创建新项目

    • 登录 GitLab → New project → Create blank project。
    • 填写项目名称（如 my-blog），可见性选择 Public。
    • 重要：项目名称需与 Hexo 的 _config.yml 中配置的路径一致（默认无需修改）。

  2. 本地关联 GitLab 仓库

    1
    2
    git init
    git remote add origin https://gitlab.com/你的用户名/my-blog.git

四、配置 Hexo 部署到 GitLab

  1. 安装 Hexo Git 部署插件

    1
    npm install hexo-deployer-git --save

  2. 修改 Hexo 配置文件
    打开 _config.yml，找到 deploy 部分，修改为：

    1
    2
    3
    4
    deploy:
      type: git
      repo: https://gitlab.com/你的用户名/my-blog.git
      branch: main  # GitLab 默认分支是 main，不是 master！

  3. 测试部署

    1
    hexo clean && hexo generate --deploy
    • 此命令会将生成的静态文件（在 public 目录下）推送到 GitLab 的 main 分支。
    • 但为了自动化构建，建议使用 GitLab CI/CD（见下一步）。

五、配置 GitLab CI/CD 自动化部署

  1. 创建 .gitlab-ci.yml 文件
    在项目根目录新建文件，内容如下：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    image: node:16  # 使用 Node.js 16 环境

    pages:
      cache:
        paths:
          - node_modules/  # 缓存依赖加速构建
      script:
        - npm install
        - npm install hexo-cli -g  # 全局安装 Hexo
        - hexo generate  # 生成静态文件到 public 目录
      artifacts:
        paths:
          - public  # GitLab Pages 默认从 public 目录部署
      only:
        - main  # 仅 main 分支触发构建

  2. 推送代码到 GitLab

    1
    2
    3
    git add .
    git commit -m "初始化 Hexo 博客"
    git push -u origin main

  3. 查看构建状态

    • 进入 GitLab 项目 → CI/CD → Pipelines，查看流水线状态。
    • 构建成功后，进入 Settings → Pages，确认网站地址。

六、访问博客

  • 默认地址：

    1
    https://你的用户名.gitlab.io/my-blog
    • 如果项目名称为 my-blog，访问路径需包含项目名。
    • 如果希望直接使用 https://你的用户名.gitlab.io，需将项目重命名为 你的用户名.gitlab.io（如 john.gitlab.io）。

七、自定义域名（可选）

  1. 购买域名
    在域名服务商（如 GoDaddy、阿里云）购买域名（如 example.com）。

  2. 配置 DNS 解析

    • 添加 CNAME 记录：

      1
      2
      3
      主机名：blog  
      类型：CNAME  
      值：你的用户名.gitlab.io

    • 或添加 A 记录：

      1
      2
      3
      主机名：@  
      类型：A  
      值：35.185.44.232（GitLab Pages 的 IP）

  3. GitLab 配置自定义域名

    • 进入项目 → Settings → Pages → New Domain。

    • 输入域名（如 blog.example.com），点击 Save。

    • 在 Hexo 的 source 目录下创建 CNAME 文件（无后缀），内容为域名：

      1
      blog.example.com

    • 推送代码使配置生效：

      1
      2
      3
      git add source/CNAME
      git commit -m "添加自定义域名"
      git push origin main

八、更新博客内容

  1. 新建文章

    1
    hexo new "我的第一篇文章"
    • 编辑文件 source/_posts/我的第一篇文章.md。

  2. 本地预览

    1
    hexo clean && hexo server

  3. 部署到 GitLab

    • 方式一：手动生成并推送

      1
      hexo clean && hexo generate --deploy

    • 方式二：触发 CI/CD 自动构建（推荐）

      1
      2
      3
      git add .
      git commit -m "添加新文章"
      git push origin main

九、常见问题解决

  1. 构建失败

    • 错误提示：npm install 失败。
      • 检查 .gitlab-ci.yml 中的 Node.js 版本是否与本地一致。
    • 错误提示：hexo generate 报错。
      • 确保 _config.yml 中语法正确（避免使用 Tab 缩进，需用空格）。

  2. 页面 404

    • 原因：访问路径错误。
      • 如果项目名为 my-blog，访问地址应为 https://用户名.gitlab.io/my-blog。
      • 若希望根路径访问，需将项目重命名为 用户名.gitlab.io。

  3. 自定义域名不生效

    • 检查 CNAME 文件是否提交到仓库。
    • 等待 DNS 解析生效（最长可能需要 48 小时）。

按照以上步骤，你可以将 Hexo 博客无缝部署到 GitLab Pages，享受免费、稳定的静态网站托管服务！

部署Github方式部署到Gitlab

  1. 在_config.yml中增加部署仓库链接

  2. 新建.gitlab-ci.yml文件用于触发流水线

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    pages:
    stage: deploy
    script:
        - mkdir .public
        - cp -r ./* .public
        - rm -rf public
        - mv .public public
    artifacts:
        paths:
        - public
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  3. 在执行完hexo g后先将.gitlab-ci.yml复制到.deploy_git中再执行hexo d

官方方式

  1. 如果你更希望你的站点部署在 <你的 GitLab 用户名>.gitlab.io 的子目录中，你的 repository 需要直接命名为子目录的名字，这样你的站点可以通过 https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字> 访问。 你需要检查你的 Hexo 配置文件，将 url 的值修改为 https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字>、将 root 的值修改为 /<repository 的名字>/

  2. 通过 Settings > CI/CD > Runners > Enable shared runners for this project 启用共享运行程序。

  3. 将你的 Hexo 站点文件夹推送到 repository 中。 默认情况下 public 目录将不会（并且不应该）被推送到 repository 中，建议你检查 .gitignore 文件中是否包含 public 一行，如果没有请加上。 整体文件夹结构应该与 示例储存库 大致相似。

  4. 使用 node --version 指令检查你电脑上的 Node.js 版本。 记下主要版本（例如，v16.y.z）

  5. 将 .gitlab-ci.yml 文件添加到您的版本库根目录（与 _config.yml & package.json并列），内容如下（将16替换为您在上一步中注意到的 Node.js 主版本）

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    image: node:16-alpine
    cache:
    paths:
        - node_modules/

    before_script:
    - npm install hexo-cli -g
    - npm install

    pages:
    script:
        - npm run build
    artifacts:
        paths:
        - public
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  6. GitLab CI 应该会自动开始运行，构建成功以后你应该可以在 https://<你的 GitLab 用户名>.gitlab.io 查看你的网站。