Cursor开发Hexo博客全记录

我与 AI 助手：从零到一搭建个人博客的完整记录

前言：一直想拥有一个属于自己的博客，用来记录技术和生活。作为一名开发者，我决定使用 Hexo 静态博客框架，并借助 AI 助手 Cursor 来完成整个搭建过程。这篇文章，便是我与 AI “拉扯”与协作，从环境配置到深度主题定制的全程实录。

阶段一：启程与第一个“下马威”

User
我打算使用 Hexo 框架和 NexT 主题制作一个个人博客网站，最终目标是能通过 Git 一键部署到 GitHub Pages。请你根据我的计划，进行一个完整的项目规划。

Cursor
好的，以下是根据你的需求制定的完整项目规划，涵盖了从技术选型、开发流程到注意事项的全部内容。

个人博客网站开发完整规划

  1. 项目整体架构
    • 技术选型: Hexo, NexT 主题 (后更换为 Anzhiyu), Node.js, Git, GitHub Pages, Giscus 评论系统。
    • 主要功能: 文章发布、主题美化、本地搜索、评论系统、一键部署。
  2. 开发关键节点
    • 环境初始化 -> 主题安装 -> 核心配置 -> 内容创建 -> 功能增强 -> 部署配置 -> 上线。
  3. 注意事项
    • 所有占位符（如 GitHub 用户名）需替换为个人实际信息。
    • GitHub 仓库需提前创建，格式为 your-username.github.io。
    • 建议使用 Node.js 的 LTS 版本。

确认规划后，我们即可开始第一步。

User
好的，我开始了。
…
运行 npm install hexo-cli -g 命令报错如下，请你分析原因并给出解决方案：

1
npm error ENOTEMPTY: directory not empty, rename '/Users/your-name/.../hexo-cli' -> '/Users/your-name/.../.hexo-cli-XXXX'

Cursor
这个报错通常是因为之前安装 hexo-cli 时异常中断，导致有残留文件。

解决方案：

  1. 手动删除残留目录：
    1
    2
    3
    # 请根据你的实际报错路径修改
    rm -rf /Users/your-name/.../hexo-cli
    rm -rf /Users/your-name/.../.hexo-cli-*
  2. 再次全局安装：
    1
    npm install hexo-cli -g
    如果遇到权限问题，可以尝试在命令前加 sudo。

阶段二：网络问题与主题安装

User
环境初始化与项目创建已完成，可以进入下一步了。

Cursor
好的，现在我们进入 步骤 2：安装并启用主题。

  1. 下载主题：在项目根目录下执行：
    1
    git clone https://github.com/next-theme/hexo-theme-next.git themes/next
  2. 启用主题：打开项目根目录下的 _config.yml 文件，将 theme: 字段修改为 next。

User
运行 git clone 命令报错，请你分析并给出解决方案。

1
fatal: unable to access 'https://github.com/next-theme/hexo-theme-next.git/': Error in the HTTP2 framing layer

我浏览器访问 GitHub 正常，我使用了代理，但终端似乎没走代理。

Cursor
感谢你的详细反馈！这是典型的终端网络代理问题。浏览器和终端的代理设置是分开的。

解决方案：

  1. 为 Git 单独配置代理（推荐）：
    假设你的代理端口是 7890（请根据你的实际情况修改）：

    1
    2
    3
    4
    5
    6
    7
    # HTTP 代理
    git config --global http.proxy http://127.0.0.1:7890
    git config --global https.proxy http://127.0.0.1:7890

    # 如果是 SOCKS5 代理
    git config --global http.proxy 'socks5://127.0.0.1:7890'
    git config --global https.proxy 'socks5://127.0.0.1:7890'

    配置完成后，再执行 git clone 命令。

  2. 使用国内镜像源（备选方案）：

    1
    git clone https://mirrors.tuna.tsinghua.edu.cn/git/hexo/theme-next.git themes/next

阶段三：部署与认证的“世纪难题”

User
所有配置都完成了，现在准备部署。

Cursor
收到，现在我们进入部署环节。首先安装 Git 部署插件，然后在 _config.yml 中配置好你的 GitHub 仓库地址。

User
运行 hexo deploy 命令后提示报错，请你分析并提出解决方案。

1
2
remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed for 'https://github.com/your-username/your-username.github.io.git/'

Cursor
这个报错的原因是，GitHub 在 2021 年后就不再支持使用账户密码来推送代码了，必须使用 Personal Access Token (个人访问令牌) 或 SSH key 进行身份验证。

推荐使用 SSH Key，更安全也更方便。

User
我 GitHub 上之前好像申请过一个 SSH Key，此时需要重新 New 一个吗？以及我需要执行“生成 SSH Key”这一步吗？我找不到 ~/.ssh/id_ed25519.pub 这个文件。

Cursor
你的问题很细致，我来一步步教你。

  1. 是否需要新建？
    如果本地已经有 SSH Key，不需要新建。我们先来检查一下。

  2. 检查本地是否已有 SSH Key
    在终端输入：ls ~/.ssh。如果输出中有 id_ed25519.pub 或 id_rsa.pub，说明你已经有了。

  3. 复制公钥内容
    用 cat ~/.ssh/id_rsa.pub 命令查看并复制公钥内容。

  4. 添加公钥到 GitHub
    将复制的内容粘贴到 GitHub 的 Settings -> SSH and GPG keys 页面。

  5. 修改 Hexo 部署配置为 SSH 格式
    打开 _config.yml，将 repo 字段改为 SSH 格式：

    1
    2
    3
    4
    deploy:
      type: git
      repo: git@github.com:your-username/your-username.github.io.git
      branch: main

  6. 测试并重新部署

    • 测试连接：ssh -T git@github.com
    • 重新部署：hexo clean && hexo generate && hexo deploy

User
我本地终端运行 cat ~/.ssh/id_rsa.pub 命令后是有输出的，但是我添加 SSH Key 到 GitHub 并保存时，提示 Key is already in use，我该怎么做？

Cursor
这个提示说明你的这把 SSH 公钥已经被添加到你的 GitHub 账号了。

你现在该这么做：

  1. 无需重复添加，直接用它进行认证即可。
  2. 检查 deploy 配置，确保 repo 字段是 SSH 格式 git@github.com:...。
  3. 测试 SSH 连接，运行 ssh -T git@github.com，如果返回 Hi your-username! You've successfully authenticated... 就说明配置完全没问题。
  4. 重新部署，运行 hexo clean && hexo generate && hexo deploy。

User
提示我“Congratulations, you’re all set!”，似乎已经成功了。

阶段四：一个“简单”的在线写作功能探索

User
现在如果要在博客网站上写文章太复杂了，我得先用 IDE 打开文件夹，然后用复杂的命令行指令来完成。你能够尝试在博客网站上直接添加写作功能吗？

Cursor
你的需求非常常见。Hexo 作为静态博客，本身不支持在线写作，但我们可以通过第三方插件 hexo-admin 来实现一个本地的可视化后台。

  1. 在博客根目录安装 hexo-admin：
    1
    npm install hexo-admin --save
  2. 启动 Hexo 本地服务：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
        hexo server
        ```3.  访问 `http://localhost:4000/admin`，即可进入后台管理界面。

    **User**
    `hexo server` 运行后访问 `http://localhost:4000/admin`，提示 `Cannot GET /admin`。

    **Cursor**
    这个问题很常见，通常是插件没有被正确加载。我检查了一下，`hexo-admin` 这个插件比较老，对新版本的 Hexo 兼容性不佳。你用的是 Hexo 7.x 吗？

    **User**
    是的，我使用的是 Hexo 7.x，所以需要降级吗？具体该怎么做，降级后会影响其他内容吗？

    **Cursor**
    是的，建议降级到 Hexo 5.x，兼容性最好。

    *   **降级会影响内容吗？**
        **不会**。你的文章、页面、主题都在 `source/` 和 `themes/` 目录下，与 Hexo 版本无关。

    *   **具体步骤**：
        1.  **卸载当前 Hexo 7.x**：
            ```bash
            npm uninstall hexo
    1. 安装 Hexo 5.x（推荐 5.4.2）：
      1
      npm install hexo@5.4.2 --save
    2. 重新安装 hexo-admin:
      1
      npm install hexo-admin --save
    3. 重启服务：hexo clean && hexo server。

阶段五：主题深度定制的“分类”拉锯战

User
目前博客网站一进入就是一篇文章，没有首页吗？以及我想修改主题该怎么样让它更专业更好看呢？

Cursor
Hexo 默认首页就是文章列表页，你只看到一篇是因为你只写了一篇。多写几篇就会变成列表了。
关于主题美化，你正在使用的 Anzhiyu 主题支持高度自定义。我们可以从分类显示逻辑开始优化。

User
我设置了二级分类，比如文章的 front-matter 里写 categories: [大学, 大学生涯]，但是 category-bar（分类栏）上同时显示了“大学”和“大学生涯”，这样子感觉更怪了，怎么办？

Cursor
你遇到的问题是 Hexo 会将每一级分类都单独作为一个节点显示。我们可以通过修改主题模板，让分类栏只显示一级分类。

  1. 定位模板文件：分类栏的渲染逻辑在 themes/anzhiyu/scripts/helpers/catalog_list.js。
  2. 修改渲染逻辑：我们找到 catalog_list 这个 helper 函数，在 map 函数前加上 filter，只筛选出没有父级的分类（即一级分类）。
    1
    2
    3
    hexo.locals.get(type)
      .filter(item => !item.parent) // 只保留一级分类
      .map(function (item) { /*...*/ });
    这样，分类栏就只会显示“大学”这个一级分类了。

User
这样修改后，点击 category-bar 的“大学”进入的是“分类-大学”页面，但点击我自己在首页顶部配置的“大学”按钮，进入的还是“分类-大学生涯”页面。我感觉逻辑有问题。

Cursor
你的感觉是对的，原因是：同一个“大学”按钮，category-bar 和首页顶部按钮跳转到的不是同一个页面，用户体验不一致。

推荐做法：统一它们的 path，都指向一级分类页面 /categories/大学/。
修改 _config.anzhiyu.yml 文件中，首页顶部按钮的 path：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- name: 大学
  path: /categories/大学/ # 原来可能是 /categories/大学/大学生涯/```
这样无论点击哪里，都进入“大学”这个总的分类页面，逻辑就通顺了。

**User**
对，这样修改后逻辑没有问题了。那如果我希望进入 `/categories/大学/` 页面后，可以进一步筛选该一级分类下的二级分类的文章，我具体该怎么做呢？

**Cursor**
这个需求很棒！我们需要修改分类页面的模板，让它在一级分类页面上，自动渲染出其下属的所有二级分类列表。

1.  **定位分类页面模板**：`themes/anzhiyu/layout/category.pug`

2.  **在模板中插入二级分类渲染逻辑**：
    在 `category.pug` 文件中合适的位置（如标题下方），插入以下 Pug 代码：
    ```pug
    // 显示二级分类
    - var currentCategory = site.categories.data.find(c => c.name === page.category);
    if currentCategory && currentCategory.children && currentCategory.children.length
      .sub-categories
        h3 二级分类
        ul
          each child in currentCategory.children
            li
              a(href=url_for('/categories/' + encodeURIComponent(currentCategory.name) + '/' + encodeURIComponent(child.name) + '/'))= child.name
  1. 添加自定义 CSS 样式：
    为了让二级分类列表更美观，可以在 themes/anzhiyu/source/css/_extra/fix/ 目录下新建一个 CSS 文件（主题会自动加载），并添加一些美化样式。
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    .sub-categories {
      margin: 1.5em 0;
      padding: 1em;
      background: var(--anzhiyu-card-bg);
      border-radius: 8px;
    }
    .sub-categories a {
      display: inline-block;
      padding: 0.3em 1em;
      border-radius: 5px;
    }
    .sub-categories a:hover {
      background: var(--anzhiyu-theme);
      color: #fff;
    }

User
如图，这是进入“大学”后的画面，但我刚才不是让你在这个页面再加上筛选 sub-categories 分类的按钮吗，为什么目前没有看到？

image

Cursor
你的截图显示了 Pug 代码没有被正确渲染。这通常是 Pug 对缩进极其敏感导致的，或者是数据获取方式有细微差别。

解决办法：
请严格检查 category.pug 中插入代码的缩进，并确保使用 site.categories.data 来获取分类数据。

1
2
3
// 修正后的代码
- var currentCategory = site.categories.data.find(c => c.name === page.category);
// ...

同时，为了调试，你可以在页面上临时输出变量，看看是否成功获取到了分类和子分类的数量。

1
2
3
// 调试代码
p= '调试：' + (currentCategory ? currentCategory.name : '未找到')
p= '子分类数：' + (currentCategory && currentCategory.children ? currentCategory.children.length : '无')

通过这样的调试和修正，最终二级分类筛选区域就能成功显示出来了。

后记：至此，我的个人博客不仅成功上线，还具备了相当不错的定制化功能。整个过程充满了发现问题、分析问题、解决问题的循环，AI 助手在其中扮演了知识库、调试伙伴和代码生成器的多重角色。这趟旅程，收获匪浅。