技术博客

新手从零搭建技术博客（避坑版）

作为刚上手搭建技术博客的新手，我们从「完全不懂Hexo」到「成功部署上线，适配电脑+手机端」，踩了无数没必要的坑，耗时整整半天。这篇文章会把我们的真实操作步骤、每一步的细节，以及踩过的所有坑（含解决方案）全部整理出来，新手跟着走，不用走弯路，一次性搭建成功！

核心目标：搭建一个基于Hexo的静态技术博客，支持本地预览、阿里云服务器部署，电脑端+手机端适配，能正常发布文章、插入图片。

适用人群：零基础新手（不懂前端、不懂服务器、不懂命令行），全程复制命令即可操作，无需额外学习复杂知识。

目录

  1. 前置准备（必做，少一步都不行）

  2. 第一步：安装基础环境（Node.js + Git）

  3. 第二步：安装Hexo，初始化博客

  4. 第三步：配置Hexo基础信息（修改博客名称、作者等）

  5. 第四步：发布第一篇测试文章

  6. 第五步：本地预览博客（验证效果）

  7. 第六步：阿里云服务器部署（让所有人都能访问）

  8. 第七步：手机端适配（解决侧边栏在底部的问题）

  9. 我们踩过的10个致命坑（新手必看，避免踩雷）

  10. 后续优化建议（简单易操作，提升博客体验）

一、前置准备（必做，少一步都不行）

在开始操作前，先准备好以下东西，避免操作到一半卡壳：

  • 一台Windows电脑（本文全程基于Windows操作，Mac步骤类似，命令略有差异）

  • 一个阿里云服务器（新手推荐轻量应用服务器，系统选择CentOS 7/8，无需配置复杂环境）

  • 服务器的IP地址、root账号密码（购买服务器后，在阿里云控制台查看）

  • 一个域名（可选，没有域名也能通过服务器IP访问，有域名更方便记忆，比如我们的www.subencai.cn

  • 耐心！新手操作难免出错，遇到报错不要慌，对照后面的「踩坑记录」找解决方案即可。

二、第一步：安装基础环境（Node.js + Git）

Hexo运行依赖Node.js和Git，必须先安装这两个工具，否则无法执行后续命令。全程傻瓜式安装，下一步即可。

2.1 安装Git

  1. 下载Git安装包：打开官网 https://git-scm.com/download/win，选择「64-bit Git for Windows Setup」下载（无需注册，直接下载）。

  2. 安装Git：双击安装包，全程点击「下一步」，唯一需要注意的是——在「Select Components」步骤，勾选「Add Git to PATH」（让系统能识别Git命令，避免后续报错）。

  3. 验证Git是否安装成功：打开Windows开始菜单，搜索「PowerShell」，打开后输入命令 git --version，如果显示Git版本号（比如git version 2.43.0），说明安装成功。

2.2 安装Node.js

  1. 下载Node.js安装包：打开官网 https://nodejs.org/zh-cn/download/，选择「LTS版本」（长期支持版，更稳定，适合新手），下载64位安装包。

  2. 安装Node.js：双击安装包，全程点击「下一步」，同样注意——勾选「Add to PATH」，让系统能识别node和npm命令。

  3. 验证Node.js是否安装成功：在PowerShell中输入命令 node -v 和 npm -v，如果分别显示Node.js和npm的版本号，说明安装成功。

三、第二步：安装Hexo，初始化博客

基础环境安装完成后，开始安装Hexo，初始化我们的个人博客。全程在PowerShell中执行命令，复制粘贴即可，不要手动输入（避免输错符号）。

3.1 安装Hexo-cli（Hexo命令行工具）

在PowerShell中输入以下命令，安装Hexo命令行工具（全局安装，以后任何目录都能使用Hexo命令）：

1
npm install -g hexo-cli

安装过程可能需要1-2分钟，耐心等待，出现「added x packages」说明安装成功（如果出现警告，不用管，不影响使用）。

3.2 初始化博客目录

  1. 先创建一个博客目录（建议放在C盘根目录，方便查找），比如 C:\hexo_blog：

     `mkdir C:\hexo_blog`

  2. 进入博客目录：cd C:\hexo_blog

  3. 初始化Hexo博客（这一步会自动创建博客所需的所有文件和文件夹）：

     `hexo init`

  4. 安装博客依赖包（初始化完成后，执行以下命令）：

     `npm install`

执行完成后，打开 C:\hexo_blog 目录，能看到以下文件夹/文件，说明初始化成功：

  • source：存放文章、图片等资源（以后写的文章都放在这里）

  • themes：存放博客主题（默认是landscape主题）

  • _config.yml：博客核心配置文件（修改博客名称、作者等都在这里）

四、第三步：配置Hexo基础信息（修改博客名称、作者等）

初始化完成后，我们需要修改博客的基础信息，让博客变成自己的，比如博客名称、作者、描述等。

  1. 打开博客核心配置文件：C:\hexo_blog\_config.yml（用记事本、Typora都能打开，推荐用Typora，格式更清晰）。

  2. 找到以下配置项，修改成自己的信息（注意：配置项后面的冒号 : 后面必须加一个空格，否则会报错，这是新手最容易踩的坑之一）：

     `# Site

    title: 我的技术博客 # 博客名称，比如「XX的技术笔记」
    subtitle: 记录技术成长，分享学习心得 # 博客副标题
    description: 专注于Java、运维、云服务器相关技术分享 # 博客描述（可选）
    author: 你的名字 # 你的名字
    language: zh-CN # 语言，中文填zh-CN
    timezone: Asia/Shanghai # 时区，填Asia/Shanghai`

  3. 修改完成后，按 Ctrl+S 保存文件。

五、第四步：发布第一篇测试文章

配置完成后，我们发布第一篇测试文章，看看博客的效果。Hexo提供了快速创建文章的命令，无需手动创建文件。

  1. 在PowerShell中，确保当前目录是 C:\hexo_blog，执行以下命令，创建一篇标题为「Hello World」的测试文章：

     `hexo new "Hello World"`

  2. 找到这篇文章：文章会自动生成在 C:\hexo_blog\source\_posts 目录下，文件名是 Hello World.md（Markdown格式，新手可以用Typora编辑）。

  3. 编辑文章：打开 Hello World.md，可以修改内容，比如：

     `---

    title: Hello World
    date: 2026-02-27 15:00:00
    tags: [Hexo, 新手教程]
    categories: 技术博客

我的第一篇技术博客

大家好，这是我用Hexo搭建的第一篇测试文章！

以后我会在这里分享我的技术学习心得、项目实战经验，欢迎大家关注～`

  1. 保存文章（Ctrl+S），关闭编辑器。

六、第五步：本地预览博客（验证效果）

文章编辑完成后，我们可以在本地预览博客的效果，确认没有问题后，再部署到服务器。

  1. 在PowerShell中，执行以下命令，生成静态文件并启动本地服务器：

     `# 生成静态文件（把Markdown文章转换成HTML文件）

    hexo generate

启动本地服务器（默认端口4000）

hexo server`

  1. 预览博客：打开电脑浏览器，输入 http://localhost:4000，就能看到自己的博客了！

    • 首页会显示我们刚刚发布的「Hello World」文章；

    • 右侧是侧边栏（文章列表、分类、标签）；

    • 点击文章标题，能进入文章详情页。

  2. 停止本地服务器：如果想修改文章或配置，需要先停止服务器，按 Ctrl+C 即可停止。

七、第六步：阿里云服务器部署（让所有人都能访问）

本地预览没问题后，我们把博客部署到阿里云服务器，这样任何人通过服务器IP（或域名）都能访问我们的博客。核心是「把本地生成的静态文件，上传到服务器的网站根目录」。

7.1 服务器端准备（先配置服务器，允许访问）

我们需要先在服务器上创建网站根目录，配置权限，避免上传文件后无法访问。

  1. 登录阿里云服务器：用Xshell、Putty等SSH工具登录（新手推荐用Xshell，可视化操作更简单），输入服务器IP、root账号和密码，登录成功后，进入服务器命令行。

  2. 创建网站根目录（用于存放博客静态文件）：

     `# 创建目录（路径可以自定义，我们用这个路径，后续统一）

    mkdir -p /var/blog/public`

  3. 配置目录权限（避免上传文件后无法访问，新手直接执行即可）：

     `chmod -R 755 /var/blog/public`

7.2 本地上传静态文件到服务器

我们用 scp 命令（Git自带），把本地 public 目录（Hexo生成的静态文件）上传到服务器的 /var/blog/public 目录。

  1. 在本地PowerShell中，停止本地服务器（Ctrl+C），执行以下命令，重新生成最新的静态文件：

     `hexo clean && hexo generate`（hexo clean 是清理缓存，避免旧文件干扰，每次上传前都建议执行）

  2. 执行上传命令（复制粘贴，替换里面的服务器IP）：

     `scp -r public\* root@你的服务器IP:/var/blog/public/`示例：如果你的服务器IP是114.55.242.250，命令就是：`scp -r public\* root@114.55.242.250:/var/blog/public/`

  3. 输入服务器root密码：执行命令后，会提示输入root密码，输入时不会显示密码（正常现象），输入完成后按回车，开始上传。

  4. 上传完成：看到PowerShell中显示文件列表滚动，最后没有报错，说明上传成功。

7.3 验证服务器部署效果

上传完成后，打开浏览器，输入你的服务器IP（比如 http://114.55.242.250），就能看到你的博客了！

如果无法访问，大概率是阿里云服务器的安全组没有开放80端口（网页访问默认端口），解决方法：

  1. 登录阿里云控制台，找到你的服务器，点击「安全组」；

  2. 点击「配置规则」，添加一条入站规则：端口范围填80，授权对象填0.0.0.0/0（允许所有IP访问）；

  3. 保存规则，等待1-2分钟，再刷新浏览器，就能正常访问了。

八、第七步：手机端适配（解决侧边栏在底部的问题）

部署完成后，用手机访问博客会发现一个问题：侧边栏（文章列表、分类）被挤到了页面最底部，用户需要翻完所有文章才能看到导航，体验极差。我们结合自己的踩坑经历，给出最简单的适配方案，新手直接复制代码即可。

7.1 确认主题文件（landscape主题）

Hexo默认主题是landscape，我们的适配代码针对这个主题，如果你用的是其他主题，步骤略有差异。先确认主题目录：C:\hexo_blog\themes\landscape，里面有 source\css\style.styl 和 source\js\script.js 两个文件（如果没有，参考前面的「重新安装主题」步骤）。

7.2 修改样式文件（style.styl）

  1. 打开文件：C:\hexo_blog\themes\landscape\source\css\style.styl；

  2. 找到文件末尾的移动端媒体查询（类似 @media (max-width: 800px)），把这段代码完全替换成以下代码：

    @media (max-width: 800px) {
  .container {
    display: flex;
    flex-direction: column;
    width: auto;
    margin: 0 auto;
    padding: 0 10px;
  }

  .content {
    width: auto;
    float: none;
    padding: 0;
    order: 1;
  }

  .sidebar {
    width: auto;
    float: none;
    margin-left: 15px;
    padding: 0 15px;
    background: #f8f8f8;
    border-radius: 8px;
    border: 1px solid #eee;
    order: -1;
    margin-bottom: 20px;
  }

  body {
    font-size: 16px;
    line-height: 1.6;
  }

  .post-content {
    font-size: 16px;
  }

  .widget {
    margin-bottom: 10px;
    border-bottom: 1px solid #eee;
    padding-bottom: 10px;
  }

  .widget-title {
    cursor: pointer;
    padding: 8px 0;
    font-size: 18px;
    font-weight: bold;
    color: #333;
  }

  .widget-content {
    display: none;
    padding-left: 5px;
  }

  .widget.active .widget-content {
    display: block;
  }

  .widget-title::before {
    content: "▶";
    font-size: 12px;
    color: #666;
    transition: transform 0.3s;
  }

  .widget.active .widget-title::before {
    content: "▼";
    transform: rotate(90deg);
  }
}

  3. 保存文件（Ctrl+S）。

7.3 修改JS文件（script.js）

  1. 打开文件：C:\hexo_blog\themes\landscape\source\js\script.js；

  2. 把以下代码复制到文件最后一行：

    // 移动端侧栏折叠菜单
$(window).on('resize', function() {
  if ($(window).width() <= 800) {
    $('.widget-title').off('click').on('click', function() {
      $(this).parent('.widget').toggleClass('active');
    });
    $('.widget').removeClass('active');
    $('.widget:first').addClass('active');
  } else {
    $('.widget-title').off('click');
    $('.widget').addClass('active');
  }
});

// 初始化移动端 widget
function initMobileWidget() {
  if ($(window).width() <= 800) {
    $('.widget-title').off('click').on('click', function() {
      $(this).parent('.widget').toggleClass('active');
    });
    $('.widget').removeClass('active');
    $('.widget:first').addClass('active');
  } else {
    $('.widget-title').off('click');
    $('.widget').addClass('active');
  }
}

// 页面加载完成后初始化
initMobileWidget();
$(window).resize(initMobileWidget);

    保存文件（Ctrl+S）。

7.4 重新上传到服务器

修改完成后，重新生成静态文件并上传到服务器，让适配生效：

1
2
hexo clean && hexo generate
scp -r public\* root@你的服务器IP:/var/blog/public/

验证效果：用手机访问你的博客IP，会发现侧边栏（文章列表）移到了正文上方，点击标题可折叠/展开，不用再翻到底部，体验大幅提升。

九、我们踩过的10个致命坑（新手必看，避免踩雷）

这部分是我们搭建过程中，实际踩过的坑，每一个都让我们卡壳半小时以上，整理出来，新手可以直接避开，节省时间。

坑1：Node.js安装后，PowerShell中输入node -v报错「不是内部或外部命令」

原因：安装Node.js时，没有勾选「Add to PATH」，系统无法识别node命令。

解决方案：重新安装Node.js，安装时务必勾选「Add to PATH」；如果已经安装，重启电脑后再试（重启后系统会加载环境变量）。

坑2：修改_config.yml后，hexo generate报错「YAMLException: duplicated mapping key」

原因：配置文件中，同一个配置项出现了两次（比如我们之前重复添加了include配置），YAML格式不允许重复键。

解决方案：打开_config.yml，搜索报错的配置项（比如include），删除重复的那一段，只保留一个即可。

坑3：图片插入后，本地预览和服务器都显示不出来

原因：Windows默认隐藏文件扩展名，导致图片文件名变成「xxx.png.png」（双后缀），而文章中引用的是「xxx.png」，路径不匹配。

解决方案：打开文件夹，点击顶部「查看」，勾选「文件扩展名」，把所有图片的双后缀改成单后缀（比如arch.png.png → arch.png）；同时确保图片引用路径正确（参考前面的图片配置步骤）。

坑4：hexo generate后，public目录中没有images文件夹，图片无法生成

原因：Hexo默认不会复制source/images目录到public，需要在_config.yml中添加配置，强制Hexo包含该目录。

解决方案：打开_config.yml，找到「include」配置项，修改为：
`include:

  • images/**`

坑5：服务器部署后，浏览器访问IP显示404

原因：1. 静态文件没有上传到服务器的网站根目录；2. 服务器安全组没有开放80端口；3. 文件权限不足。

解决方案：
确认上传命令正确，静态文件已上传到/var/blog/public目录；在阿里云控制台开放80端口（入站规则）；执行命令 chmod -R 755 /var/blog/public，修复文件权限。

坑6：手机端侧边栏在底部，修改CSS后没有效果

原因：主题自带的移动端CSS优先级更高，我们追加的代码被覆盖了；或者修改的是style.css，而主题实际使用的是style.styl（Stylus预处理器）。

解决方案：找到theme/landscape/source/css/style.styl，直接替换主题自带的移动端媒体查询代码（参考第七步），不要追加。

坑7：hexo server启动后，访问localhost:4000显示空白页

原因：1. 没有生成静态文件（未执行hexo generate）；2. 文章格式错误（Markdown语法错误，比如—分隔符缺失）。

解决方案：先执行hexo generate，再启动服务器；检查文章的Markdown格式，确保开头的—分隔符正确，没有语法错误。

坑8：scp上传文件时，报错「ssh: connect to host xxx.xxx.xxx.xxx port 22: Connection refused」

原因：服务器的22端口（SSH端口）没有开放，或者服务器防火墙禁止了22端口访问。

解决方案：在阿里云安全组中，添加入站规则，开放22端口（授权对象0.0.0.0/0）；如果修改过SSH端口，需要在上传命令中指定端口（比如scp -P 端口号 …）。

坑9：重新安装landscape主题后，找不到style.styl文件

原因：没有正确克隆官方主题，导致主题文件缺失。

解决方案：执行以下命令，重新克隆官方主题：
cd C:\hexo_blog Remove-Item -Recurse -Force themes git clone https://github.com/hexojs/hexo-theme-landscape.git themes/landscape

坑10：修改主题后，本地预览有效果，服务器端没有效果

原因：修改主题后，没有重新生成静态文件，或者没有把最新的public目录上传到服务器。

解决方案：每次修改主题、文章后，都要执行 hexo clean && hexo generate，然后重新上传到服务器，覆盖原有文件。

十、后续优化建议（简单易操作，提升博客体验）

博客搭建完成后，可以做一些简单的优化，提升用户体验，新手也能轻松操作：

  1. 绑定域名：如果有域名，在阿里云控制台解析域名到服务器IP，让用户能通过域名访问（比如www.你的域名.com），比IP更易记。

  2. 添加文章分类和标签：写文章时，在Markdown开头添加tags和categories，方便用户查找相关文章（比如tags: [Hexo, 运维]，categories: 技术笔记）。

  3. 修改博客主题：如果不喜欢默认的landscape主题，可以在Hexo官网找其他免费主题，替换themes目录即可（注意：不同主题的配置方式略有差异）。

  4. 添加图片懒加载：在script.js中添加简单的懒加载代码，让博客加载更快（适合图片较多的文章）。

  5. 定期备份：把博客目录（C:\hexo_blog）备份到云盘，避免误删文件，导致博客丢失。

总结

新手搭建技术博客，核心就是「安装环境→初始化博客→发布文章→部署服务器→适配移动端」，看似复杂，但只要跟着步骤走，复制命令、修改配置，就能一次性成功。

我们踩过的坑，本质上都是「细节问题」——比如配置文件的空格、文件扩展名、端口开放、权限设置，这些都是新手容易忽略的点，但只要避开这些坑，搭建过程会非常顺利。

搭建完成后，坚持发布技术文章，记录自己的学习成长，你的技术博客会慢慢成为自己的「技术知识库」，也能帮助到更多和你一样的新手。如果在搭建过程中遇到其他问题，欢迎留言交流，我们会尽力帮忙解决！