第七章：博客部署与上线——一步步教你搞定

发表于2024-08-08|更新于2025-03-24|科技·Techhexo

|浏览量:

Hexo建设个人网站系列教程目录

第七章：博客部署与上线——一步步教你搞定

一、部署前的准备

在正式将博客部署到线上之前，我们需要确保以下几项内容都已准备完毕：
1.1 安装 Hexo 及必要依赖

在本地搭建 Hexo 博客前，务必确保你已经安装了 Node.js 和 Git。如果尚未安装，可以参考以下步骤：

安装 Node.js
    请前往 Node.js 官网 下载并安装最新的 LTS 版本。
    安装完成后，通过命令行执行 node -v 和 npm -v 来验证安装情况。

安装 Git
    请访问 Git 官网 下载安装包并按照提示完成安装。
    安装后，在命令行执行 git --version 检查是否安装成功。

安装 Hexo CLI
打开命令行工具，输入以下命令安装 Hexo 命令行工具：

npm install -g hexo-cli

安装完毕后，使用 hexo -v 检查版本信息，确保安装成功。

1.2 初始化 Hexo 博客项目

如果你还没有初始化博客项目，请在命令行中选择一个目录，然后运行：

hexo init my-blog
cd my-blog
npm install

初始化完成后，你可以通过 hexo server 命令启动本地服务器，在浏览器中访问 http://localhost:4000 查看博客效果。
1.3 配置 _config.yml

在 Hexo 博客的根目录下，有一个 _config.yml 文件，该文件包含了博客的基本配置。请确保你已经根据需要修改了博客的标题、作者、语言、根目录、部署相关的配置等。特别注意的是在部署部分，我们需要在 _config.yml 文件中增加或修改 deploy 部分的配置，例如对于 GitHub Pages 部署：

deploy:
type: git
repo: https://github.com/你的用户名/你的仓库名.git
branch: gh-pages

如果你是使用其他平台部署，请参考对应平台的要求修改配置。
1.4 注册及配置 GitHub 账号（或其他主机账户）

如果你计划将博客部署到 GitHub Pages，需要有一个 GitHub 账号，并创建一个对应的仓库。步骤如下：

注册 GitHub 账号
访问 GitHub 官网 完成账号注册，若已有账号请跳过此步骤。

创建仓库
登录 GitHub 后，点击右上角的 “New repository” 按钮，输入仓库名称（例如 my-blog），并选择仓库公开（Public Repository），仓库名称建议与 _config.yml 中的 repo 保持一致。

生成 SSH Key（可选）
为了更安全地进行推送操作，你可以在本地生成 SSH Key，并添加到 GitHub 账号中。生成命令如下：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

根据提示生成后，将 ~/.ssh/id_rsa.pub 文件中的内容复制到 GitHub 的 SSH keys 设置中。

1.5 其他第三方主机准备工作

如果你选择将博客部署到其他主机，例如 Vercel、Netlify、Coding Pages 或者阿里云 OSS 等，请确保你已经注册了对应平台的账号，并熟悉部署文档。每个平台的部署方式略有不同，通常需要上传静态文件并配置域名解析。
二、部署步骤详解

本节我们以 GitHub Pages 为例，详细介绍如何将 Hexo 博客部署到 GitHub Pages。其他平台的部署方法大同小异，可参考对应平台的文档。
2.1 安装 Hexo 部署插件

Hexo 提供了多种部署插件，GitHub Pages 需要使用 hexo-deployer-git 插件。你可以通过 npm 安装：

npm install hexo-deployer-git –save

安装完成后，再次检查 _config.yml 中的 deploy 配置是否正确。
2.2 配置 Git 仓库地址

在 _config.yml 文件中，部署部分通常需要配置如下：

deploy:
type: git
repo: https://github.com/你的用户名/你的仓库名.git
branch: gh-pages

如果你使用 SSH 方式，repo 地址可以改为：

repo: git@github.com:你的用户名/你的仓库名.git

请确保仓库地址和分支名称正确，通常 GitHub Pages 默认使用 gh-pages 分支，但有时也可以选择 master 或 main 分支。
2.3 执行部署命令

完成配置后，在博客项目根目录中，执行以下命令生成静态文件并部署到 GitHub 仓库：

hexo clean && hexo generate && hexo deploy

这条命令会依次清理缓存、生成静态页面并将内容推送到远程仓库。部署完成后，你可以在 GitHub 仓库中查看是否新增了 gh-pages 分支，或者查看提交记录是否更新。
2.4 验证部署结果

部署完成后，访问以下链接验证是否上线成功：

如果仓库地址为 https://github.com/你的用户名/你的仓库名.git，则访问 https://你的用户名.github.io/你的仓库名/；
如果你采用自定义域名（后续章节详细介绍），则直接访问绑定的域名地址。

2.5 使用 GitHub Actions 实现自动部署（进阶）

为了让部署流程更加自动化，你可以使用 GitHub Actions 来实现代码提交后自动部署。创建一个 GitHub Actions 配置文件 .github/workflows/hexo-deploy.yml，内容示例如下：

name: Hexo Deploy

on:
push:
branches:
- main # 或者你使用的主分支名称

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2

- name: Setup Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '14'

- name: Install dependencies
  run: npm install

- name: Generate static files
  run: npx hexo generate

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages

将该文件提交到 GitHub 后，每次提交到 main 分支时，GitHub Actions 会自动生成并部署博客到 gh-pages 分支，省去了手动部署的步骤。
三、域名绑定

部署成功后，若想使用个性化域名访问博客，需要进行域名绑定设置。以下步骤将指导你如何在 GitHub Pages 上绑定自定义域名。
3.1 域名购买与解析设置

购买域名
通过阿里云、腾讯云、Namecheap 或其他域名注册商购买你心仪的域名。

域名解析设置
登录域名注册商后台，在 DNS 管理中添加解析记录。若你希望将域名直接指向 GitHub Pages，可以添加如下记录：
    A记录
    指向 GitHub Pages 的 IP 地址：
        185.199.108.153
        185.199.109.153
        185.199.110.153
        185.199.111.153
        这四个 IP 地址可以根据需要都添加，保证访问稳定性。
    CNAME记录
    若你的域名为二级域名（例如 blog.example.com），则添加一条 CNAME 记录，将其指向 你的用户名.github.io。
    注意：如果使用 A 记录，必须确保域名的解析类型与 GitHub 的要求一致，防止 HTTPS 证书无法签发的问题。

3.2 在 GitHub 仓库中添加 CNAME 文件

在项目根目录中创建 CNAME 文件
在 Hexo 博客项目的根目录中创建一个名为 CNAME 的文件，文件中写入你要绑定的域名，例如：

www.example.com

注意：该文件必须放在生成的 public 目录中，确保每次部署后该文件被上传到 GitHub Pages 仓库中。

重新部署博客
完成 CNAME 文件配置后，再次执行：

hexo clean && hexo generate && hexo deploy

部署完成后，在 GitHub 仓库的 gh-pages 分支中会看到 CNAME 文件。GitHub Pages 将根据该文件识别并绑定你的自定义域名。

3.3 配置 HTTPS

绑定域名后，为了保证安全，建议启用 HTTPS 访问。进入 GitHub 仓库的 “Settings” -> “Pages”，在自定义域名区域勾选 “Enforce HTTPS”。GitHub 会自动为你的域名申请免费的 Let’s Encrypt 证书，通常需要等待一段时间后生效。
四、常见问题排查与解决方案

在博客部署过程中，可能会遇到各种问题。以下列出了一些常见问题及其解决方案，帮助你快速定位并解决问题。
4.1 部署命令执行出错

问题描述：
执行 hexo deploy 命令时出现报错，如 “fatal: repository not found” 或 “Permission denied”。

解决方案：

检查 _config.yml 中 deploy 部分的 repo 地址是否正确。若使用 HTTPS 地址，请确保 GitHub 账号拥有该仓库的写权限；若使用 SSH 地址，请确认 SSH Key 配置正确。
执行 git remote -v 检查远程仓库配置是否存在问题，如发现错误请使用以下命令修改：

git remote set-url origin https://github.com/你的用户名/你的仓库名.git

4.2 部署后网站无法访问

问题描述：
部署完成后，访问博客地址提示 404 或者无法加载页面。

解决方案：

分支检查：
请确认部署的目标分支是否正确。例如 GitHub Pages 默认要求部署到 gh-pages 分支，若你部署到其他分支，请在仓库的 “Settings” -> “Pages” 中调整设置。
CNAME 文件问题：
如果使用自定义域名，确保 CNAME 文件存在且内容正确。你可以在仓库中直接检查 CNAME 文件，确认是否为你想要绑定的域名。
缓存问题：
有时浏览器缓存会导致页面加载不正确，请尝试清除浏览器缓存或使用无痕模式访问网站。
生成文件问题：
若生成的静态文件内容不完整，尝试执行 hexo clean 后重新生成部署。

4.3 HTTPS 启用失败

问题描述：
在 GitHub Pages 配置中，HTTPS 选项无法启用或一直处于等待状态。

解决方案：

DNS 配置检查：
请确保域名解析记录已正确指向 GitHub Pages 的 IP 地址，并且解析生效。DNS 更改通常需要几分钟到 48 小时生效。
CNAME 文件检查：
确认 CNAME 文件内容与 DNS 记录保持一致，避免因域名不匹配导致 HTTPS 申请失败。
等待时间：
有时 GitHub 需要一定时间来处理 HTTPS 申请，请耐心等待，通常数小时后即可自动启用。

4.4 部署自动化失败（GitHub Actions）

问题描述：
使用 GitHub Actions 自动部署时出现构建失败、部署步骤中断或文件缺失等问题。

解决方案：

日志检查：
进入 GitHub 仓库的 “Actions” 标签页，查看最新的构建日志。日志中会明确提示错误信息，根据信息进行修正。
依赖问题：
确保仓库中 package.json 文件中所有依赖都已正确声明，部分插件版本冲突可能导致构建失败。
目录结构检查：
在部署步骤中，确保 public 目录存在且包含所有生成的静态文件。你可以在本地运行 hexo generate 后检查 public 目录的内容，再对比 GitHub 仓库中的文件是否一致。

4.5 部署到其他平台的常见问题

如果你选择将 Hexo 部署到其他平台，如 Netlify、Vercel、Coding Pages 或阿里云 OSS，也可能遇到以下问题：

构建失败：
确保平台支持 Node.js 环境，并且在配置文件中指定了正确的构建命令，例如：

npm install && hexo generate

文件上传不完整：
检查平台部署配置，确保所有生成的文件都已上传。部分平台可能需要手动设置上传目录，确保上传目录为 public 文件夹。
域名绑定问题：
每个平台域名绑定方式有所不同，请参考平台文档配置正确的 DNS 记录，并确保平台管理后台中的域名设置与实际解析一致。

五、进阶技巧与优化建议

部署成功只是第一步，接下来你可以通过一些进阶技巧和优化建议让你的博客体验更佳、运行更稳定。
5.1 部署脚本自动化

为了避免手动输入多条命令，可以编写一个部署脚本，例如 deploy.sh 文件，内容如下：

#!/bin/bash
echo “开始清理旧文件…”
hexo clean
echo “开始生成静态文件…”
hexo generate
echo “开始部署到远程仓库…”
hexo deploy
echo “部署完成！”

将脚本保存后，赋予执行权限：

chmod +x deploy.sh

以后每次只需运行 ./deploy.sh 即可自动完成所有部署步骤。
5.2 使用 CI/CD 提高部署效率

除了 GitHub Actions 外，还有 Travis CI、CircleCI、GitLab CI 等持续集成工具也能实现自动部署。选择适合你的工具，配置好构建和部署流程，可以大大提高更新博客的效率和稳定性。
5.3 备份与版本管理

在每次部署前，建议做好代码备份与版本管理。通过 Git 的分支管理、标签标记等机制，可以轻松回溯历史版本，防止出现错误后无法恢复的情况。常用命令：

git add .
git commit -m “更新博客内容”
git push origin main

同时，定期备份 Hexo 的配置文件、主题配置文件以及自定义插件，以免丢失宝贵的个性化设置。
5.4 优化生成速度与性能

随着博客内容的增多，生成静态文件的速度可能会变慢。以下几种方法可以帮助你优化生成速度：

文章分页：
配置 Hexo 分页功能，减少每次生成的文件数量，提高生成速度。
增量生成：
对于频繁更新的博客，利用增量生成插件只更新改变的部分。
缓存机制：
利用 Hexo 的缓存机制（如 hexo-cache）存储未更改的页面，减少重复生成时间。

5.5 SEO 优化与第三方插件扩展

上线后，你可以关注博客的 SEO 优化，提升搜索引擎的收录效果。常见优化措施包括：

配置友好的 URL 结构
添加站点地图（Sitemap）插件
使用 Meta 标签优化文章描述与关键字
集成 Google Analytics 或其他流量统计工具

另外，Hexo 社区中有大量优秀的插件，可以扩展博客功能，如评论系统、代码高亮、文章分享等。探索社区资源，让你的博客更具吸引力与互动性。
六、综合部署案例示例

下面将以一个完整的部署案例帮助你更直观地理解整个流程。假设你的博客项目名为 my-hexo-blog，目标仓库为 https://github.com/yourusername/my-hexo-blog.git，你希望部署到 gh-pages 分支，并使用自定义域名 www.example.com。
6.1 修改 _config.yml 部署部分

deploy:
type: git
repo: git@github.com:yourusername/my-hexo-blog.git
branch: gh-pages

6.2 在项目根目录创建 CNAME 文件

在 source 或 public 目录下（推荐放在 public 目录中），新建一个名为 CNAME 的文件，内容为：

www.example.com

6.3 执行本地部署

在命令行中执行：

hexo clean && hexo generate && hexo deploy

部署完成后，请访问 https://www.example.com 检查网站是否正常显示。
6.4 通过 GitHub Actions 实现自动部署

在项目根目录下创建 .github/workflows/hexo-deploy.yml 文件，内容如下：

name: Hexo Deploy

on:
push:
branches:
- main

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v2

- name: Setup Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '14'

- name: Install Dependencies
  run: npm install

- name: Generate Site
  run: npx hexo generate

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages

提交此文件后，每次向 main 分支推送更新时，GitHub Actions 将自动构建并部署网站。
七、部署注意事项及常见误区

在部署过程中，除了技术细节，许多初学者还可能遇到一些常见误区，以下是一些你需要特别注意的事项：
7.1 部署路径与 URL 配置不一致

误区：
未正确配置 Hexo 根路径（root）或部署的仓库路径，导致生成的静态文件中 URL 地址不正确，访问时出现 404 错误。
建议：
仔细核对 _config.yml 中的 root 配置，若你的博客并非部署在根目录下，而是某个子目录下（例如 /blog/），请将 root 设置为 /blog/。同时确保部署仓库的文件结构与预期一致。

7.2 未及时更新 Hexo 插件或主题

误区：
使用旧版本的 Hexo 或插件可能导致部署过程中出现意外错误或安全隐患。
建议：
定期检查并更新 Hexo 及相关插件，确保使用最新的稳定版本。

7.3 忽视日志与错误提示

误区：
部署过程中出现报错信息时，很多人往往直接尝试重新部署而不认真分析错误日志，导致问题无法解决。
建议：
仔细查看终端输出的错误提示，根据提示信息逐步定位问题所在。如果是依赖问题、路径错误或权限问题，往往可以从日志中找到关键线索。

7.4 域名解析设置错误

误区：
自定义域名解析时，未按照要求设置 A 记录或 CNAME 记录，导致绑定失败。
建议：
核对域名注册商的 DNS 解析设置，确认所有记录均指向 GitHub Pages 的官方 IP 地址或正确的目标地址。必要时，可借助在线 DNS 工具检查解析结果。

八、常见问题问答（FAQ）

为了更直观地帮助大家理解，下面列出一些常见问题的问答形式：
Q1：为什么我部署后访问自定义域名时仍然显示 GitHub 默认页面？

A1：请确认仓库中是否存在正确的 CNAME 文件，同时检查 DNS 解析是否生效。建议使用 DNS 检查工具验证你的域名解析记录是否正确指向 GitHub Pages 的 IP 地址。
Q2：执行 hexo deploy 后提示 “fatal: Authentication failed” 该如何解决？

A2：这通常是因为你的 GitHub 认证信息配置不正确。建议检查是否使用了正确的 HTTPS 或 SSH 地址。如果使用 HTTPS，可能需要生成 GitHub Token 替代密码；如果使用 SSH，请确认你的公钥已经添加到 GitHub 账户中。
Q3：自动部署的 GitHub Actions 失败，如何调试？

A3：进入 GitHub 仓库的 “Actions” 选项卡，查看失败任务的详细日志信息。根据日志提示，检查 Node.js 版本、依赖安装情况以及 publish_dir 是否正确指向生成的 public 文件夹。
Q4：博客内容更新后，网站显示仍然是旧内容，怎么办？

A4：这可能是浏览器缓存问题。建议清理浏览器缓存或尝试无痕模式访问。同时确保每次更新后执行了 hexo clean 命令，以避免缓存文件的干扰。
九、总结与后续优化

在本章节中，我们从部署前的各项准备工作开始，详细讲解了如何将本地 Hexo 博客部署到 GitHub Pages（或其他主机），包括配置文件设置、部署命令执行、域名绑定、HTTPS 配置以及常见问题的排查和解决。经过一系列操作，你的博客将能够稳定、安全地在线公开访问。

部署成功后，你可以进一步关注以下几个方面进行优化和扩展：

自动化更新： 利用 CI/CD 工具实现每次更新自动部署，降低人工干预风险。
安全性加强： 定期检查 GitHub 仓库的安全设置，确保 SSH 密钥、访问令牌等信息不外泄。
性能监控： 部署后可以利用第三方工具监控网站访问速度、错误日志以及流量数据，持续优化博客体验。
内容扩展： 随着博客内容不断丰富，定期优化站内搜索、文章分类和标签，使用户能够更便捷地查找内容。

通过本文提供的详细步骤与解决方案，相信你已经掌握了 Hexo 博客从本地生成到部署上线的完整流程。无论你是初次尝试还是希望进一步优化博客部署流程，都可以参考本文中的案例与技巧，实现博客的稳定运行与高效更新。

希望本章节内容能帮助你顺利将 Hexo 博客部署到线上，享受技术带来的便利与成就感！如有其他问题或遇到特殊情况，欢迎参考 Hexo 官方文档以及 GitHub Pages 的相关帮助文档，或在技术社区寻求更多支持与帮助。

通过以上详细的讲解与示例代码，你应能清晰地了解如何将 Hexo 博客部署到线上，并解决部署过程中可能遇到的各种问题。接下来，不妨动手试试，将你的博客内容推送到线上，与全球读者分享你的技术见解和生活点滴。祝你部署顺利，博客大卖！

文章作者: Chan Revival

文章链接: https://www.crsky.uk/posts/hexo-jian-she-ge-ren-wang-zhan-xi-lie-jiao-cheng-7.bo-ke-bu-shu-yu-shang-xian-yi-bu-bu-jiao-ni-gao-ding.html