从 0 到 1：如何真正上线一个属于自己的博客

写在前面

这篇文章记录我使用 Hexo + Stellar + 宝塔面板 + Nginx + Twikoo，从零开始搭建并上线个人博客的完整过程。它不是一份只展示成功结果的说明书，也包含我真正遇到过的问题：配置文件报错、部署速度很慢、域名解析不会选、评论在本地正常但其他人无法使用、关闭代理后请求失败，以及图片太大导致网站加载缓慢。

如果你也准备搭建自己的第一个博客，希望这篇记录能让你少绕一些路。

一、先理解博客是怎样上线的

在开始安装之前，最好先理解整个链路：

1
2
3
4
5
6
7
8
9
10
11
12
13

本地编写 Markdown 文章
        ↓
Hexo 生成静态网页
        ↓
将 public 中的文件部署到服务器
        ↓
Nginx 对外提供网页
        ↓
域名解析到服务器 IP
        ↓
配置 HTTPS
        ↓
访客通过域名访问博客

Hexo 本身不是一个一直运行在服务器上的后台程序。它更像一个“网页生成器”：我们在本地写 Markdown，Hexo 将文章、主题和配置转换成 HTML、CSS、JavaScript 等静态文件，然后把这些文件交给 Nginx 展示。

因此，真正需要放到服务器上的，通常是 Hexo 生成的 public 目录中的内容，而不是整个 Hexo 项目。

二、我的技术方案

这次博客使用的主要工具如下：

博客的内容定位是技术、学习与摄影，因此我没有把它做成纯技术文档站，而是在 Stellar 原有结构上加入了偏蓝、清透、低饱和的颜色，以及摄影页、欢迎区、字体和局部动效。

一个很重要的经验是：先让博客正常运行和上线，再逐步做视觉定制。 如果一开始同时修改主题、部署、域名和评论系统，出现错误时会很难判断问题来自哪里。

三、准备本地环境

1. 安装 Node.js 和 Git

先在电脑上安装 Node.js 和 Git。安装完成后，在 PowerShell 中检查：

1
2
3

node -v
npm -v
git --version

只要都能正常输出版本号，就说明基础环境已经准备完成。

2. 安装 Hexo

1

npm install -g hexo-cli

检查 Hexo 是否安装成功：

1

hexo version

3. 初始化博客项目

选择一个准备存放博客代码的位置：

1
2
3

hexo init blog
cd blog
npm install

然后启动本地预览：

1

hexo server

浏览器访问：

1

http://localhost:4000

看到 Hexo 默认页面，就说明本地博客已经成功运行。

如果提示端口被占用，可以换一个端口：

1

hexo server -p 5000

这时访问 http://localhost:5000 即可。

四、安装并配置 Stellar 主题

1. 安装主题

在 Hexo 项目根目录执行：

1

npm install hexo-theme-stellar

然后打开 Hexo 根目录下的 _config.yml，修改主题：

1

theme: stellar

重新生成并预览：

1
2
3

hexo clean
hexo generate
hexo server

2. 区分两个配置文件

使用 Stellar 时，经常会接触两个配置文件：

• _config.yml：Hexo 整个站点的基础配置，例如网址、目录、部署方式。
• _config.stellar.yml：Stellar 主题配置，例如导航、侧栏、颜色、评论和字体。

修改时要特别注意 YAML 的缩进。YAML 不使用大括号区分层级，而是依靠空格，所以同一层级的缩进必须保持一致，并且不能在同一个层级重复定义相同的键。

例如，下面的写法会报 duplicated mapping key：

1
2
3
4
5

comments:
  service: twikoo

comments:
  lazyload: true

正确做法是合并为一个 comments：

1
2
3

comments:
  service: twikoo
  lazyload: true

遇到 YAML 报错时，先看终端给出的行号，不要急着重装主题。大多数情况下只是缩进错误或键名重复。

3. 添加自己的文章

创建一篇新文章：

1

hexo new "我的第一篇文章"

文章会出现在：

1

source/_posts/我的第一篇文章.md

常见的文章头部信息如下：

1
2
3
4
5
6
7
8
9
10

---
title: 我的第一篇文章
date: 2026-08-17 16:00:00
categories:
  - 技术分享
tags:
  - Hexo
  - 博客搭建
comments: true
---

之后就可以在下方使用 Markdown 正常写作。

五、定制博客，但不要破坏主题结构

我希望博客既能放技术文章，也能展示摄影作品，因此没有完全照搬现成模板，而是在 Stellar 的基础上做定制。

我主要修改了这些内容：

• 站点标题、副标题和头像；
• 首页欢迎区与导航；
• 偏蓝、清透、低饱和的配色；
• 正文字体、字号和阅读宽度；
• 技术文章的分类颜色；
• 摄影作品页和图片布局；
• 适量的悬停效果与背景动效。

自定义 CSS 可以放在：

1

source/css/custom.css

然后通过 Stellar 的注入配置引入。为了避免浏览器一直使用旧缓存，可以在文件地址后添加版本号：

1
2
3

inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css?v=20260817">

每次大幅修改样式后更新版本号，浏览器就会重新请求 CSS 文件。

需要注意的是，Stellar 已经处理了大量响应式布局。修改页面宽度、侧栏距离和定位时，尽量覆盖少量变量或选择器，不要一开始就重写整套布局，否则很容易出现电脑端正常、手机端错位的问题。

六、生成可部署的网站文件

每次准备部署前，执行：

1
2

hexo clean
hexo generate

也可以使用简写：

1
2

hexo clean
hexo g

成功后，项目根目录会出现 public 文件夹。

先打开 public/index.html 或重新运行本地预览，确认页面没有明显问题。public 中的文件就是接下来需要部署到服务器的成品。

七、通过宝塔和 Nginx上线博客

我的服务器使用 CentOS，并通过宝塔面板管理。对第一次部署博客的人来说，宝塔的图形界面比直接编写 Nginx 配置更容易理解。

1. 在宝塔中新建站点

进入宝塔面板后：

1. 打开“网站”；
2. 点击“添加站点”；
3. 填写自己的域名；
4. 选择“纯静态”站点；
5. 记录网站根目录，例如 /www/wwwroot/blog.example.com。

这里不需要创建数据库，因为 Hexo 生成的是静态网站。

2. 上传网站文件

进入站点根目录，删除宝塔自动创建的默认页面，然后上传 Hexo 的生成结果。

最容易出错的是目录层级。

正确结构应该是：

1
2
3
4

/www/wwwroot/blog.example.com/index.html
/www/wwwroot/blog.example.com/css/
/www/wwwroot/blog.example.com/js/
/www/wwwroot/blog.example.com/images/

而不是：

1

/www/wwwroot/blog.example.com/public/index.html

也就是说，要上传的是 public 文件夹里面的全部内容，而不是把 public 文件夹整体再套一层放进去。

上传后可以暂时使用服务器 IP 或宝塔提供的站点访问方式检查页面。若首页显示 404，优先检查站点根目录和 index.html 是否位于正确层级。

八、配置域名解析

域名解析的作用，是告诉浏览器“这个域名应该访问哪台服务器”。

1. 博客主域名使用 A 记录

如果博客部署在自己的云服务器上，通常添加 A 记录：

• @ 通常表示根域名，例如 example.com；
• blog 表示子域名，例如 blog.example.com。

2. 第三方服务自定义域名通常使用 CNAME

A 记录和 CNAME 记录不能混用：

• A 记录指向一个 IPv4 地址；
• CNAME 记录指向另一个域名。

例如，Twikoo 后端若托管在第三方平台，并要求为 twikoo.example.com 添加 CNAME，就应在域名当前实际使用的权威 DNS 平台中添加，而不是一定要在购买服务器的平台添加。

如果某个控制台中只能看到 A 记录，先检查域名的 DNS 服务器到底由哪家平台管理。域名在哪里买、服务器在哪里买、DNS 在哪里管理，可能是三件不同的事。

DNS 修改后不会永远立即生效，通常需要等待解析缓存更新。

九、为博客开启 HTTPS

域名解析生效后，可以在宝塔站点设置中申请 Let’s Encrypt 证书：

1. 打开对应站点的“设置”；
2. 进入“SSL”；
3. 选择 Let’s Encrypt；
4. 勾选需要签发证书的域名；
5. 申请并部署证书；
6. 确认 HTTPS 可以访问后，再开启“强制 HTTPS”。

不要在证书尚未签发成功时急着开启强制 HTTPS，否则可能出现 HTTP 和 HTTPS 都无法正常访问的情况。

同时要检查 Hexo 根目录 _config.yml 中的网址：

1

url: https://blog.example.com

修改后重新执行：

1
2

hexo clean
hexo generate

并再次部署生成文件。

十、接入 Twikoo 评论系统

静态博客本身没有数据库和后台，因此不能独立保存评论。Twikoo 的作用就是为静态页面补充评论能力。

在 Stellar 中，通常需要启用 Twikoo，并填写后端地址 envId。具体字段以当前主题配置为准，核心逻辑类似：

1
2
3
4

comments:
  service: twikoo
  twikoo:
    envId: https://twikoo.example.com

具体操作可以参考这篇文章

十一、解决图片过大和部署缓慢

摄影博客很容易出现一个问题：原图清晰，但体积也非常大。我最初的部分 JPG 图片接近 10 MB，多张图片一起放入 public 后，会带来三个后果：

• hexo deploy 上传时间明显增加；
• 网页首屏加载缓慢；
• 手机流量消耗大，图片解码也更慢。

博客展示图通常不需要保留相机原图的完整尺寸。更合理的做法是：

1. 保留原图作为本地备份；
2. 另存一份博客展示版本；
3. 将长边控制在适合网页展示的范围；
4. JPG 使用适度压缩，或转换为 WebP；
5. 在保证观感的前提下，将单张图片尽量控制在几百 KB 到 1～2 MB 内；
6. 为图片设置懒加载，避免进入页面时一次加载全部照片。

可以先检查生成目录中最大的文件。在 PowerShell 中执行：

1
2
3
4
5

Get-ChildItem .\public -Recurse -File |
Sort-Object Length -Descending |
Select-Object -First 20 `
@{Name="大小MB";Expression={[math]::Round($_.Length / 1MB, 2)}},
FullName

如果部署突然变得很慢，先检查是否刚加入了大图、视频或字体文件，再考虑是不是服务器或 Git 出了问题。

另外，如果服务器在国内而电脑开启了绕行海外的代理，上传流量可能走更远的路径，反而导致部署速度下降。遇到 Broken pipe、Connection reset by peer 或 send-pack disconnect 时，可以关闭代理后重试，并先压缩过大的静态资源。

十二、我的日常更新流程

博客上线后，每次更新文章可以遵循固定流程：

1
2
3
4
5
6
7
8
9
10
11

# 1. 本地预览
hexo server

# 2. 清理旧缓存
hexo clean

# 3. 生成静态文件
hexo generate

# 4. 部署
hexo deploy

也可以简写为：

1
2
3

hexo clean
hexo g
hexo d

如果暂时使用宝塔手动上传，就在生成后压缩 public 中的内容，再上传并解压到站点根目录。等整个流程稳定以后，再配置 Git 自动部署，不需要在第一次上线时同时解决所有自动化问题。

建议同时用 Git 保存 Hexo 源码，但不要只保存生成后的 public。真正重要的是：

• source/ 中的文章和图片；
• _config.yml；
• _config.stellar.yml；
• source/css/custom.css；
• 自己添加的页面、数据和脚本；
• package.json 与锁文件。

不要将服务器密码、宝塔安全入口、Token、私钥和数据库凭据写进公开仓库或教程截图。

十三、常见问题速查

1. YAMLException: duplicated mapping key

同一个 YAML 文件的同一层级出现了两个相同键名。根据报错行号找到它们，将配置合并，不要只删除其中一段需要的内容。

2. 本地样式修改有效，线上没有变化

依次检查：

1. 是否重新执行了 hexo clean 和 hexo generate；
2. 是否上传了最新 public；
3. CSS 引用路径是否正确；
4. 是否被浏览器或 CDN 缓存；
5. 是否更新了 custom.css 后的版本号。

3. 服务器首页显示 404

检查 index.html 是否直接位于站点根目录，而不是位于多套一层的 public 中；同时检查宝塔站点设置中的根目录是否正确。

宝塔某个端口的根路径返回 404，也不一定代表面板服务没有运行。如果忘记正确入口，可以在服务器终端使用宝塔提供的管理命令查看，而不要把安全入口公开在文章或截图中。

4. 评论只有自己能用

不要只在一台电脑和同一个网络下测试。关闭代理，使用手机流量或其他网络访问，并检查 Twikoo 后端域名在这些环境中是否可达。

5. 部署速度突然很慢

优先检查最近新增的图片、视频和字体大小；再检查代理路径、服务器网络和 Git 连接。不要把所有问题都归因于 Hexo。

6. hexo server 提示端口被占用

关闭之前未退出的 Hexo 进程，或者使用其他端口：

1

hexo server -p 5000

十四、上线前检查清单

正式分享博客地址前，我建议逐项检查：

• 首页、文章页、分类页、标签页可以打开；
• 电脑端和手机端布局正常；
• 域名 A 记录已指向正确服务器；
• HTTPS 证书有效，HTTP 能正确跳转；
• Hexo 中的 url 已改为正式 HTTPS 域名；
• 图片路径、字体和自定义 CSS 没有 404；
• 评论可以在无代理网络和手机流量下提交；
• 页面中没有暴露 Token、密码和后台入口；
• 大图已经压缩，首屏加载速度可以接受；
• 源码和文章已经用 Git 或其他方式备份；
• 用无痕窗口测试过一次完整访问流程。