Blog Developing process

发表于 2025-07-27

个人博客网站开发规划

Exported on 2025/7/27 at GMT+8 18:21:39 from Cursor (1.2.1)

User

我打算制作一个个人博客网站，下面是完整的个人博客开发计划，请你结合下面的开发计划，首先对该个人博客网站开发做一个完整的规划，等待我同意后再开始具体进行开发。

一、项目目标

使用 Hexo 框架和 NexT 主题，初始化并配置一个静态个人博客。项目最终配置为通过 Git 一键部署到 GitHub Pages。

二、技术栈

框架: Hexo

主题: Hexo Theme NexT

运行环境: Node.js

版本控制 & 部署: Git & GitHub Pages

评论系统: Giscus (基于 GitHub Discussions)

内容格式: Markdown

三、执行步骤

步骤 1：环境初始化与项目创建

执行以下命令，完成 Hexo 环境安装和项目初始化。

Generated bash

1. 全局安装 Hexo-CLI

npm install hexo-cli -g

2. 初始化博客项目并进入目录

hexo init personal-blog && cd personal-blog

3. 安装项目依赖

npm install

步骤 2：安装并启用 NexT 主题

执行以下命令，下载 NexT 主题。

Generated bash

在项目根目录（personal-blog）下执行

git clone https://github.com/next-theme/hexo-theme-next.git themes/next
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

然后，修改项目根目录下的 _config.yml 文件，启用主题：

Generated yaml

_config.yml

… (找到 theme 字段)

theme: next
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Yaml
IGNORE_WHEN_COPYING_END

步骤 3：核心站点配置

修改项目根目录下的 _config.yml 文件，填入你的个人信息。

Generated yaml

_config.yml

title: 你的网站标题
subtitle: ‘你的网站副标题’
description: ‘你的网站描述，用于SEO’
keywords:

关键词1
关键词2
author: 你的名字
language: zh-CN
timezone: ‘Asia/Shanghai’

URL (非常重要，用于部署)

url: https://你的GitHub用户名.github.io
permalink: posts/:abbrlink.html # 推荐使用更短的永久链接
permalink_defaults:
abbrlink:
alg: crc32 # 算法：crc16(default) and crc32
rep: hex # 进制：dec(default) and hex
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Yaml
IGNORE_WHEN_COPYING_END

安装永久链接插件 abbrlink：

Generated bash
npm install hexo-abbrlink –save
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

步骤 4：创建基础内容

执行以下命令，创建一篇示例文章和一个“关于”页面。

Generated bash

创建 “关于” 页面

hexo new page about

创建第一篇文章

hexo new post “我的第一篇博客”
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

步骤 5：功能配置 (评论 & 搜索)

安装搜索插件：

Generated bash
npm install hexo-generator-searchdb
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

配置主题文件 themes/next/_config.yml，开启本地搜索和 Giscus 评论。

Generated yaml

themes/next/_config.yml

Local Search

local_search:
enable: true

… (其他配置保持默认)

Comments

comments:
active: giscus # 激活 Giscus

… (其他评论系统设为 false)

Giscus Configuration

你需要先在 https://giscus.app/zh-CN 上配置好你的仓库，然后将获得的信息填入下方

giscus:
enable: true
repo: # 你的GitHub用户名/你的仓库名 (e.g., “user/repo”)
repo_id: # 你的 Repo ID
category: # 你设置的 Discussion 分类名
category_id: # 你设置的分类 ID
mapping: pathname
strict: 0
reactions_enabled: 1
emit_metadata: 0
input_position: top
theme: preferred_color_scheme
lang: zh-CN
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Yaml
IGNORE_WHEN_COPYING_END

步骤 6：配置部署

安装 Git 部署插件：

Generated bash
npm install hexo-deployer-git –save
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

修改项目根目录下的 _config.yml 文件，添加部署信息。

Generated yaml

_config.yml (文件末尾)

deploy:
type: ‘git’
repo: https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git
branch: main # 或 master，取决于你的GitHub仓库主分支名
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Yaml
IGNORE_WHEN_COPYING_END

注意：请确保你已经在 GitHub 创建了名为你的GitHub用户名.github.io 的公开仓库。

四、最终指令

当所有配置完成后，执行以下命令即可将网站生成并部署到 GitHub Pages。

Generated bash

清理旧文件、生成新网站文件、部署到GitHub

hexo clean && hexo generate && hexo deploy
IGNORE_WHEN_COPYING_START
content_copy
download
Use code with caution.
Bash
IGNORE_WHEN_COPYING_END

给用户的提示: 请将所有你的… 占位符替换为你的实际信息。Giscus 的配置信息需要在其官网获取。

Cursor

好的，以下是针对你提供的个人博客开发计划的完整项目规划，涵盖整体架构、关键节点、注意事项和后续可扩展方向。请你确认无误后，我会按照你的计划逐步协助你开发。

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

一、项目整体架构

技术选型
- 静态博客框架：Hexo
- 主题：NexT
- 运行环境：Node.js
- 版本控制与部署：Git + GitHub Pages
- 评论系统：Giscus（基于 GitHub Discussions）
- 内容格式：Markdown
目录结构（预期）
- 根目录（personal-blog）
  - source/（博客内容与页面）
  - themes/next/（NexT 主题）
  - _config.yml（全局配置）
  - package.json（依赖管理）
  - 其他 Hexo 相关目录和文件
主要功能
- 文章发布与管理
- 主题美化与自定义
- 本地搜索
- 评论系统（Giscus）
- 一键部署到 GitHub Pages

二、开发关键节点与流程

环境初始化
- 安装 Hexo CLI
- 初始化博客项目
- 安装依赖
主题安装与启用
- 下载并配置 NexT 主题
- 修改 _config.yml 启用主题
核心配置
- 填写个人信息（标题、副标题、描述、作者、语言、时区等）
- 配置永久链接（abbrlink 插件）
- 配置站点 URL（用于部署）
内容创建
- 创建“关于”页面
- 创建首篇文章
功能增强
- 安装本地搜索插件
- 配置 NexT 主题以启用本地搜索和 Giscus 评论
- 获取并填写 Giscus 配置信息
部署配置
- 安装 Git 部署插件
- 配置 _config.yml 的 deploy 字段
- 确认 GitHub 仓库已创建
一键部署
- 清理、生成、部署到 GitHub Pages

三、注意事项

所有“你的…”占位符（如 GitHub 用户名、仓库名、Giscus 配置等）需替换为你的实际信息。
Giscus 配置需提前在 giscus.app 官网获取。
GitHub 仓库需提前创建，且为公开仓库，仓库名格式为 你的GitHub用户名.github.io。
分支名（main/master）需与 GitHub 仓库实际主分支一致。
Node.js 版本建议使用 LTS 版本，避免兼容性问题。
主题和插件如有新版本，建议定期更新。

四、后续可扩展方向（可选）

绑定自定义域名
增加 RSS 订阅
站点 SEO 优化
文章分类/标签优化
主题个性化定制
增加站点统计（如 Google Analytics、百度统计等）
自动化 CI/CD 部署

请确认以上规划是否符合你的预期，或有无需要补充/调整的地方。确认后我将严格按照你的开发计划，逐步协助你完成博客的搭建与配置。

User

是的，现在请你开始具体开发，如果开发内容过多，可以分步骤开发，一步一步完成，不需要一次性完成。

Cursor

收到！我会严格按照你的开发计划，分步骤协助你完成个人博客的搭建。每一步都会详细说明操作内容和注意事项，确保你可以顺利跟进。

步骤 1：环境初始化与项目创建

1.1 全局安装 Hexo-CLI

请在终端执行以下命令，安装 Hexo 命令行工具（如已安装可跳过）：

1	npm install hexo-cli -g

1.2 初始化博客项目

在你希望存放博客的目录下，执行：

1	hexo init personal-blog && cd personal-blog

1.3 安装项目依赖

进入 personal-blog 目录后，执行：

1	npm install

进度说明

以上三步完成后，你会得到一个基础的 Hexo 博客项目，目录结构已生成，依赖已安装。
如果你在执行过程中遇到任何报错，请将报错信息发给我，我会协助你排查。

请你先完成上述步骤，并告知我进展。如果已完成或无误，我将继续进行“步骤 2：安装并启用 NexT 主题”。

1	npm install hexo-cli -g

1	hexo init personal-blog && cd personal-blog

1	npm install

User

运行npm install hexo-cli -g命令报错如下，请你分析原因并给出解决方案：

Cursor

你遇到的报错信息如下：

1	npm error ENOTEMPTY: directory not empty, rename '/Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/hexo-cli' -> '/Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/.hexo-cli-XmVeuPJU'

原因分析

这个报错通常是因为：

之前安装 hexo-cli 时中断或异常，导致 node_modules/hexo-cli 目录下有残留文件或临时文件夹。
可能有进程占用该目录，或者权限问题导致无法重命名/覆盖。

解决方案

请按以下步骤操作：

1. 手动删除残留目录

在终端执行：

1 2	rm -rf /Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/hexo-cli rm -rf /Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/.hexo-cli-*

2. 再次全局安装 Hexo-CLI

1	npm install hexo-cli -g

3. 如遇权限问题可加 sudo（仅限 Mac/Linux）

如果还是报权限相关错误，可以尝试：

1	sudo npm install hexo-cli -g

注意：如用 sudo，建议先确保 nvm 目录归属当前用户，避免后续权限混乱。

4. 检查是否有进程占用

如果依然报错，重启终端或电脑，确保没有进程占用相关目录后再试。

请先尝试上述方法，若还有问题请把新的报错信息发给我，我会继续协助你解决！

1	npm error ENOTEMPTY: directory not empty, rename '/Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/hexo-cli' -> '/Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/.hexo-cli-XmVeuPJU'

1 2	rm -rf /Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/hexo-cli rm -rf /Users/sws/.nvm/versions/node/v22.17.0/lib/node_modules/.hexo-cli-*

1	npm install hexo-cli -g

1	sudo npm install hexo-cli -g

User

运行hexo init personal-blog && cd personal-blog后，终端目前如下。我接下来该怎么做？

Cursor

很好，你已经成功执行了 hexo init personal-blog && cd personal-blog，Hexo 已经帮你初始化了博客项目，并且自动进入了 personal-blog 目录。

接下来请继续执行安装依赖这一步：

1	npm install

这条命令会自动安装 Hexo 博客所需的所有依赖包。

操作步骤：

确认你当前在 personal-blog 目录下（终端路径应该是 .../boke/personal-blog）。
直接输入并执行：
1
npm install

安装完成后，请告知我进展。如果没有报错，我会带你进入下一步“安装并启用 NexT 主题”。

1	npm install

1	npm install

User

好的，可以进入下一步了

Cursor

非常棒！你已经完成了环境初始化和依赖安装。
现在我们进入步骤 2：安装并启用 NexT 主题。

步骤 2：安装并启用 NexT 主题

2.1 下载 NexT 主题

请确保你当前在 personal-blog 项目的根目录下，然后执行：

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

这条命令会把 NexT 主题下载到 themes/next 目录。

2.2 启用 NexT 主题

用文本编辑器打开 personal-blog 目录下的 _config.yml 文件。
找到 theme: 这一行（大约在文件中部），将其修改为：
1
theme: next
保存文件。

2.3 检查主题是否生效

你可以先预览一下效果（可选）：

1	hexo server

然后在浏览器访问 http://localhost:4000 查看效果。按下 Ctrl+C 可停止本地服务。

请你先完成2.1 和 2.2，如有问题随时反馈。完成后回复我，我会带你进入核心站点配置步骤！

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

1	theme: next

1	hexo server

User

运行git clone https://github.com/next-theme/hexo-theme-next.git themes/next报错，请你分析并给出解决方案

Cursor

你遇到的报错信息如下：

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

原因分析

这个错误通常是由于网络连接异常、代理设置问题、或 GitHub 访问受限导致的。常见原因包括：

本地网络不稳定或被墙，无法正常访问 GitHub。
代理配置不当或未生效。
临时的 GitHub 服务异常（较少见）。

解决方案

1. 检查网络环境

直接在浏览器访问 https://github.com/next-theme/hexo-theme-next 看能否打开。
如果打不开，说明你的网络环境无法直接访问 GitHub，建议使用科学上网工具（如 VPN、代理等）。

2. 临时切换 Git 协议为 HTTP/1.1

有时 HTTP2 协议与部分网络环境不兼容，可以强制 Git 使用 HTTP/1.1：

1	git config --global http.version HTTP/1.1

然后再尝试克隆：

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

3. 使用镜像源（推荐国内用户）

如果你在中国大陆，建议使用清华大学开源镜像站：

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

4. 检查代理设置

如果你使用了代理，确保代理配置正确。可以尝试关闭代理后再试，或切换到其他网络环境。

5. 多试几次

有时是临时网络波动，稍等片刻后重试也可能成功。

请按上述方法逐步尝试，推荐优先使用镜像源，这样速度更快、成功率更高。如果还有问题，请把新的报错信息发给我，我会继续协助你！

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

1	git config --global http.version HTTP/1.1

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

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

User

浏览器访问 https://github.com/next-theme/hexo-theme-next可以打开，我使用了代理，但仍然无法执行git clone https://github.com/next-theme/hexo-theme-next.git themes/next命令

Cursor

感谢你的详细反馈！你能在浏览器访问 GitHub，说明代理大致可用，但 git clone 依然失败，可能是以下原因之一：

终端（命令行）未走代理：浏览器和终端的代理设置是分开的，终端未配置代理时，git 访问依然会被墙。
Git 未配置代理：即使你全局设置了代理，Git 也需要单独配置。
代理协议不兼容：有些代理只支持 HTTP/HTTPS，不支持 SOCKS5，或端口设置不对。

解决方案

1. 配置 Git 代理（以 HTTP 代理为例）

假设你的代理地址为 127.0.0.1:7890（请根据你的实际代理端口修改）：

1 2	git config --global http.proxy http://127.0.0.1:7890 git config --global https.proxy http://127.0.0.1:7890

如果你用的是 SOCKS5 代理（如 Clash、V2rayN），可以这样：

1 2	git config --global http.proxy 'socks5://127.0.0.1:7890' git config --global https.proxy 'socks5://127.0.0.1:7890'

然后再尝试克隆：

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

2. 代理软件设置

确认你的代理软件（如 Clash、Surge、Shadowrocket 等）已开启“系统代理”或“全局代理”模式。
有些代理软件需要手动勾选“允许命令行程序走代理”或“代理本地流量”。

3. 使用镜像源（推荐）

如果配置代理依然不行，直接用清华镜像源：

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

4. 取消 Git 代理（如后续不用代理）

如果后续不需要代理，可以取消：

1 2	git config --global --unset http.proxy git config --global --unset https.proxy

请你先尝试配置 Git 代理或使用镜像源，如仍有问题请反馈详细报错信息，我会继续协助你！

1 2	git config --global http.proxy http://127.0.0.1:7890 git config --global https.proxy http://127.0.0.1:7890

1 2	git config --global http.proxy 'socks5://127.0.0.1:7890' git config --global https.proxy 'socks5://127.0.0.1:7890'

1	git clone https://github.com/next-theme/hexo-theme-next.git themes/next

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

1 2	git config --global --unset http.proxy git config --global --unset https.proxy

User

2.1与2.2我都已经完成，可以继续往下了

Cursor

非常棒！你已经完成了 NexT 主题的安装与启用。
接下来进入步骤 3：核心站点配置。

步骤 3：核心站点配置

3.1 修改站点配置信息

请用文本编辑器打开 personal-blog 目录下的 _config.yml 文件，找到并修改以下字段（用你的实际信息替换）：

title: 你的博客标题
subtitle: '你的博客副标题'
description: '你的博客描述，用于SEO'
keywords:
  - 关键词1
  - 关键词2
author: 你的名字
language: zh-CN
timezone: 'Asia/Shanghai'

# URL（非常重要，用于部署）
url: https://你的GitHub用户名.github.io
permalink: posts/:abbrlink.html # 推荐使用更短的永久链接
permalink_defaults:
  abbrlink:
    alg: crc32
    rep: hex

3.2 安装永久链接插件 abbrlink

在 personal-blog 目录下执行：

1	npm install hexo-abbrlink --save

3.3 检查与保存

确认 _config.yml 文件已保存且无格式错误（YAML 缩进要对齐）。
abbrlink 插件安装无报错。

请你完成以上操作后回复我，或者如有疑问随时反馈。完成后我会带你进入内容创建步骤！

title: 你的博客标题
subtitle: '你的博客副标题'
description: '你的博客描述，用于SEO'
keywords:
  - 关键词1
  - 关键词2
author: 你的名字
language: zh-CN
timezone: 'Asia/Shanghai'

# URL（非常重要，用于部署）
url: https://你的GitHub用户名.github.io
permalink: posts/:abbrlink.html # 推荐使用更短的永久链接
permalink_defaults:
  abbrlink:
    alg: crc32
    rep: hex

1	npm install hexo-abbrlink --save

User

上述内容均已完成，可以继续往下

Cursor

非常好！你已经完成了核心站点配置和永久链接插件的安装。
接下来进入步骤 4：创建基础内容。

步骤 4：创建基础内容

4.1 创建“关于”页面

在 personal-blog 目录下执行：

1	hexo new page about

这会在 source/about 目录下生成一个 index.md 文件，你可以用 Markdown 编辑这个页面内容。

4.2 创建第一篇文章

继续执行：

1	hexo new post "我的第一篇博客"

这会在 source/_posts 目录下生成一个新的 Markdown 文件（如 我的第一篇博客.md），你可以用 Markdown 编辑你的第一篇文章内容。

4.3 可选：本地预览

你可以随时用以下命令本地预览博客效果：

1	hexo server

浏览器访问 http://localhost:4000 查看页面效果。

请你完成上述两步（4.1 和 4.2），如有问题随时反馈。完成后回复我，我会带你进入**功能配置（评论 & 搜索）**步骤！

1	hexo new page about

1	hexo new post "我的第一篇博客"

1	hexo server

User

是的，已经完成了，继续往下

Cursor

非常棒！你已经完成了基础内容的创建。
接下来进入步骤 5：功能配置（评论 & 搜索）。

步骤 5：功能配置（评论 & 搜索）

5.1 安装本地搜索插件

在 personal-blog 目录下执行：

1	npm install hexo-generator-searchdb

5.2 配置 NexT 主题以启用本地搜索和 Giscus 评论

请用文本编辑器打开 themes/next/_config.yml 文件，找到并修改以下内容：

1. 启用本地搜索

找到 local_search 字段，修改为：

1
2
3

local_search:
  enable: true
  # 其他配置保持默认即可

2. 启用 Giscus 评论

找到 comments 字段，修改为：

1
2
3

comments:
  active: giscus
  # 其他评论系统设为 false

3. 配置 Giscus

找到 giscus 字段，填写你在 giscus.app 获取的配置信息：

giscus:
  enable: true
  repo: 你的GitHub用户名/你的仓库名
  repo_id: 你的Repo ID
  category: 你的Discussion分类名
  category_id: 你的分类ID
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

注意：如暂时没有 Giscus 信息，可先留空，后续随时补充。

5.3 保存并检查

确认 themes/next/_config.yml 文件已保存且无格式错误（YAML 缩进要对齐）。
本地搜索和评论相关配置已正确填写。

请你完成上述操作后回复我，或如有疑问随时反馈。完成后我会带你进入部署配置步骤！

1	npm install hexo-generator-searchdb

1
2
3

local_search:
  enable: true
  # 其他配置保持默认即可

1
2
3

comments:
  active: giscus
  # 其他评论系统设为 false

giscus:
  enable: true
  repo: 你的GitHub用户名/你的仓库名
  repo_id: 你的Repo ID
  category: 你的Discussion分类名
  category_id: 你的分类ID
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

User

启用 Giscus 评论
找到 comments 字段，修改为：
comments:
active: giscus

其他评论系统设为 false

这一步我没懂，我找到文件中原本这块内容为如下，我该具体怎么改？

Cursor

你的疑问非常好！
你找到的 themes/next/_config.yml 文件中 comments 字段原本内容如下：

comments:
  # Available values: tabs | buttons
  style: tabs
  # Choose a comment system to be displayed by default.
  # Available values: disqus | disqusjs | changyan | livere | gitalk | utterances
  active:
  # Setting `true` means remembering the comment system selected by the visitor.
  storage: true
  # Lazyload all comment systems.
  lazyload: false
  # Modify texts or order for any naves, here are some examples.
  nav:
    #disqus:
    #  text: Load Disqus
    #  order: -1
    #gitalk:
    #  order: -2

你需要这样修改：

将 active 字段设置为 giscus
其他内容可以保持不变

修改后如下：

comments:
  style: tabs
  active: giscus
  storage: true
  lazyload: false
  nav:
    #disqus:
    #  text: Load Disqus
    #  order: -1
    #gitalk:
    #  order: -2

注意：

active: giscus 表示默认启用 Giscus 评论系统。
其他评论系统无需设置为 false，只要 active 选 giscus 即可。
后续还需要在同一文件下找到 giscus: 字段，填写你的 Giscus 相关配置信息。

如还有疑问请随时提问，完成后请告知我，咱们继续下一步！

comments:
  # Available values: tabs | buttons
  style: tabs
  # Choose a comment system to be displayed by default.
  # Available values: disqus | disqusjs | changyan | livere | gitalk | utterances
  active:
  # Setting `true` means remembering the comment system selected by the visitor.
  storage: true
  # Lazyload all comment systems.
  lazyload: false
  # Modify texts or order for any naves, here are some examples.
  nav:
    #disqus:
    #  text: Load Disqus
    #  order: -1
    #gitalk:
    #  order: -2

comments:
  style: tabs
  active: giscus
  storage: true
  lazyload: false
  nav:
    #disqus:
    #  text: Load Disqus
    #  order: -1
    #gitalk:
    #  order: -2

User

配置 Giscus这一步我没有找到giscus字段，yml文件中只有我刚才手动修改的active: giscus这一处giscus字段，我该怎么做？

Cursor

你的情况很常见，部分 NexT 主题的 _config.yml 文件默认没有 giscus: 相关配置，需要手动添加。

具体操作方法

在 themes/next/_config.yml 文件末尾（或合适位置）添加如下内容：

giscus:
  enable: true
  repo: 你的GitHub用户名/你的仓库名
  repo_id: 你的Repo ID
  category: 你的Discussion分类名
  category_id: 你的分类ID
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

请将上述内容中的“你的…”部分替换为你在 giscus.app 获取的实际信息。

示例（假设你叫 Alan，仓库名为 alan/alan.github.io）

giscus:
  enable: true
  repo: alan/alan.github.io
  repo_id: xxxxxxxx
  category: Announcements
  category_id: xxxxxxxx
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

注意事项：

giscus: 字段和 comments: 字段是同级的，不能嵌套在 comments: 下面。
YAML 缩进要严格对齐，建议用空格（不要用 Tab）。
如果暂时没有 Giscus 的 repo_id、category_id 等，可以先留空，后续随时补充。

请你将上述内容添加到 themes/next/_config.yml 文件中，保存即可。
完成后请告知我，咱们继续下一步！如有疑问也请随时提问。

giscus:
  enable: true
  repo: 你的GitHub用户名/你的仓库名
  repo_id: 你的Repo ID
  category: 你的Discussion分类名
  category_id: 你的分类ID
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

giscus:
  enable: true
  repo: alan/alan.github.io
  repo_id: xxxxxxxx
  category: Announcements
  category_id: xxxxxxxx
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: zh-CN

User

好的，下面可以进入部署配置步骤

Cursor

非常好！你已经完成了评论和搜索功能的配置。
接下来进入步骤 6：配置部署。

步骤 6：配置部署

6.1 安装 Git 部署插件

在 personal-blog 目录下执行：

1	npm install hexo-deployer-git --save

6.2 配置 `_config.yml` 部署信息

打开 personal-blog 目录下的 _config.yml 文件。
在文件末尾添加或修改如下内容（请用你的 GitHub 用户名替换）：

deploy:
  type: 'git'
  repo: https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git
  branch: main # 或 master，取决于你的 GitHub 仓库主分支名

例如，如果你的 GitHub 用户名是 alan，则应为：
1
repo: https://github.com/alan/alan.github.io.git

6.3 检查仓库

请确保你已经在 GitHub 上创建了名为 你的GitHub用户名.github.io 的公开仓库。
仓库主分支名通常为 main，如你的仓库是 master，请相应修改 branch 字段。

6.4 保存并检查

确认 _config.yml 文件已保存且无格式错误。
部署插件安装无报错。

请你完成上述操作后回复我，或如有疑问随时反馈。完成后我会带你进入最后一步：一键部署上线！

1	npm install hexo-deployer-git --save

deploy:
  type: 'git'
  repo: https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git
  branch: main # 或 master，取决于你的 GitHub 仓库主分支名

User

刚才giscus评论系统的参数我已经获取到了，如下。所以我这里的仓库并不是“名为你的GitHub用户名.github.io 的公开仓库”，与6.3步骤似乎有冲突，我该怎么做？

Cursor

你的疑问非常好，下面详细解释：

1. Giscus 评论仓库与博客部署仓库可以不同

Giscus 评论系统用的是 Discussions 功能，只要你有一个公开仓库（比如你现在用的 Alansws/Public-files-share），并在 giscus.app 上配置好即可。
博客部署仓库必须是 你的GitHub用户名.github.io 这种格式（如 Alansws/Alansws.github.io），这样 GitHub Pages 才能自动识别并发布你的博客网站。

这两个仓库可以完全不同，互不影响。

2. 你现在应该怎么做？

Giscus 配置：继续保持你现在的参数（repo 填 Alansws/Public-files-share，repo_id、category_id 等都用 giscus.app 提供的即可）。
博客部署仓库：你需要在 GitHub 上新建一个公开仓库，名字必须是 Alansws.github.io（假设你的用户名是 Alansws），用于存放博客生成的静态文件。

3. 部署配置怎么写？

在 personal-blog/_config.yml 文件末尾，deploy 字段这样写：

deploy:
  type: 'git'
  repo: https://github.com/Alansws/Alansws.github.io.git
  branch: main  # 或 master，取决于你的仓库主分支名

4. 总结

Giscus 评论仓库：可以是任意你有权限的公开仓库（如 Alansws/Public-files-share）。
博客部署仓库：必须是 Alansws.github.io，用于 GitHub Pages 展示你的博客。

请你：

在 GitHub 上新建 Alansws.github.io 公开仓库（如果还没有）。
按上述方法配置 deploy 字段。
完成后回复我，咱们进入最后一步：一键部署上线！

如有疑问请随时提问！

deploy:
  type: 'git'
  repo: https://github.com/Alansws/Alansws.github.io.git
  branch: main  # 或 master，取决于你的仓库主分支名

User

是的，已经完成

Cursor

非常棒！你已经完成了所有部署前的准备工作。
现在进入最后一步：一键部署上线。

步骤 7：生成并部署到 GitHub Pages

请在 personal-blog 目录下依次执行以下命令：

1	hexo clean && hexo generate && hexo deploy

hexo clean：清理旧的生成文件，避免缓存问题。
hexo generate：生成最新的静态网页文件。
hexo deploy：将生成的网页自动推送到你配置的 GitHub 仓库（如 Alansws.github.io）。

部署完成后

打开浏览器，访问：https://Alansws.github.io
（请用你的 GitHub 用户名替换 Alansws）
检查博客是否能正常访问，内容、主题、评论等功能是否正常。

常见问题提示

首次部署后，GitHub Pages 可能有几分钟延迟，请耐心等待。
如遇到权限、token、推送失败等问题，请将报错信息发给我，我会帮你排查。
后续每次写完新文章，只需执行 hexo generate && hexo deploy 即可自动更新博客。

请你执行上述命令并访问你的博客首页，确认无误后，个人博客的基础搭建就全部完成了！
如有任何问题或想要扩展功能（如自定义域名、SEO、统计等），随时告诉我！

1	hexo clean && hexo generate && hexo deploy

User

运行部署命令后提示报错，请你分析并提出解决方案

Cursor

你的报错信息如下：

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

原因分析

GitHub 现已不支持账户密码方式推送代码，必须使用**Personal Access Token（个人访问令牌）**或 SSH key 进行身份验证。
你当前的 Hexo 配置使用了 HTTPS 协议，但没有配置 token，导致认证失败。

解决方案一：使用 Personal Access Token（推荐）

生成 GitHub Token
- 登录 GitHub，进入 Personal Access Tokens 页面。
- 点击“Generate new token”。
- 选择 repo 权限（用于推送代码到仓库）。
- 生成后复制 token（只会显示一次）。

修改 Hexo 部署配置

打开 personal-blog/_config.yml，将 deploy 的 repo 字段改为如下格式：

deploy:
  type: git
  repo: https://<你的GitHub用户名>:<你的Token>@github.com/Alansws/Alansws.github.io.git
  branch: main

例如：

1	repo: https://Alansws:ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@github.com/Alansws/Alansws.github.io.git

注意：token 非常敏感，请勿泄露。此方法仅适合个人本地环境。

重新部署

1	hexo clean && hexo generate && hexo deploy

解决方案二：使用 SSH Key（更安全）

生成 SSH Key（如本地没有）

1	ssh-keygen -t ed25519 -C "你的邮箱"

将公钥添加到 GitHub
- 复制 ~/.ssh/id_ed25519.pub 文件内容。
- 登录 GitHub，进入 SSH and GPG keys 页面，添加新 SSH Key。

修改 deploy 配置为 SSH 格式

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

测试 SSH 连接
1
ssh -T git@github.com

重新部署

1	hexo clean && hexo generate && hexo deploy

总结

推荐第一种方法（简单直接，适合新手）。
如果你对 SSH 熟悉，建议用第二种方法（更安全，适合长期使用）。

请根据你的实际情况选择一种方法操作，遇到新问题请随时反馈！

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

deploy:
  type: git
  repo: https://<你的GitHub用户名>:<你的Token>@github.com/Alansws/Alansws.github.io.git
  branch: main

1	repo: https://Alansws:ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@github.com/Alansws/Alansws.github.io.git

1	hexo clean && hexo generate && hexo deploy

1	ssh-keygen -t ed25519 -C "你的邮箱"

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

1	ssh -T git@github.com

1	hexo clean && hexo generate && hexo deploy

User

github上我之前SSH keys有申请过一个，此时需要重新New一个新的吗？以及我需要执行“1. 生成 SSH Key（如本地没有）”这一步骤吗？复制 ~/.ssh/id_ed25519.pub 文件内容，这个文件在哪里，我找不到。请你重新具体教我怎么做

Cursor

你的问题很细致，下面我会一步一步详细教你如何用 SSH key 方式部署 Hexo 博客到 GitHub Pages。

1. 你是否需要新建 SSH Key？

如果你本地已经有 SSH key（比如 ~/.ssh/id_ed25519.pub 或 ~/.ssh/id_rsa.pub），不需要新建，直接用现有的即可。
如果你不确定本地有没有，可以先检查一下。

2. 检查本地是否已有 SSH Key

在终端输入：

ls ~/.ssh

如果输出中有 id_ed25519.pub 或 id_rsa.pub，说明你已经有 SSH key，可以直接用。

3. 如果没有 SSH Key，如何新建？

如果上一步没有 .pub 文件，说明你还没有 SSH key，需要新建：

1	ssh-keygen -t ed25519 -C "你的邮箱"

一路回车即可，默认会生成在 ~/.ssh/id_ed25519 和 ~/.ssh/id_ed25519.pub。

4. 复制公钥内容

无论是新建还是已有，公钥文件一般在：

~/.ssh/id_ed25519.pub（推荐，较新）
或 ~/.ssh/id_rsa.pub（较老）

你可以用如下命令查看并复制内容：

1	cat ~/.ssh/id_ed25519.pub

或

1	cat ~/.ssh/id_rsa.pub

把输出的内容全部复制。

5. 添加 SSH Key 到 GitHub

登录 GitHub，进入 SSH and GPG keys 页面。
点击右上角 “New SSH key”。
Title 随便填，Key 内容粘贴刚才复制的公钥内容。
保存。

6. 修改 Hexo 部署配置为 SSH 格式

打开 personal-blog/_config.yml，将 deploy 部分改为：

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

7. 测试 SSH 连接

在终端输入：

1	ssh -T git@github.com

如果提示 Hi Alansws! You've successfully authenticated...，说明 SSH 配置成功。

8. 重新部署

在 personal-blog 目录下执行：

1	hexo clean && hexo generate && hexo deploy

总结

有 SSH key 就不用新建，没有就新建。
公钥文件一般在 ~/.ssh/ 目录下，.pub 结尾的就是公钥。
添加到 GitHub 后，deploy 配置用 SSH 格式即可。

如有任何一步不明白，或遇到报错，请把终端输出发给我，我会继续帮你！

ls ~/.ssh

1	ssh-keygen -t ed25519 -C "你的邮箱"

1	cat ~/.ssh/id_ed25519.pub

1	cat ~/.ssh/id_rsa.pub

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

1	ssh -T git@github.com

1	hexo clean && hexo generate && hexo deploy

User

我的本地终端运行(base) sws@AlanswsdeMacBook-Air ~ % cat ~/.ssh/id_rsa.pub命令后是有输出的，但是我添加 SSH Key 到 GitHub并保存时，提示这个Key is already in use，我该怎么做？

Cursor

你遇到的提示“Key is already in use”说明：
你的这把 SSH 公钥已经被添加到你的 GitHub 账号（或你有权限的某个组织）中了。

你现在该怎么做？

1. 不需要重复添加

既然这把 key 已经在 GitHub 上，你无需再添加，可以直接用它进行 SSH 认证和代码推送。

2. 检查 deploy 配置

请确保你在 personal-blog/_config.yml 文件中的 deploy 配置如下（用 SSH 格式）：

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

3. 测试 SSH 连接

在终端输入：

1	ssh -T git@github.com

如果输出类似于：

1	Hi Alansws! You've successfully authenticated, but GitHub does not provide shell access.

说明 SSH 配置完全没问题。

4. 重新部署

在 personal-blog 目录下执行：

1	hexo clean && hexo generate && hexo deploy

常见问题

如果部署时仍然报错（如权限、找不到 key），请把报错信息发给我。
如果你有多个 GitHub 账号或多把 key，可能需要配置 ~/.ssh/config 文件指定使用哪把 key（如有需要我可以教你）。

总结：
你现在不需要再添加 SSH key，直接用现有的即可。只要 deploy 配置正确，SSH 连接测试通过，就可以顺利部署！

如有任何问题，随时发终端输出给我，我会继续帮你解决！

deploy:
  type: git
  repo: git@github.com:Alansws/Alansws.github.io.git
  branch: main

1	ssh -T git@github.com

1	Hi Alansws! You've successfully authenticated, but GitHub does not provide shell access.

1	hexo clean && hexo generate && hexo deploy

User

提示我“Congratulations, you’re all set!”，似乎已经成功了。因此我平时该如何来使用我的博客网站？请你具体指导我。

Cursor

恭喜你，部署成功！你的 Hexo 博客已经上线，接下来你可以愉快地写作和管理你的个人博客了。下面是详细的日常使用指南：

1. 访问你的博客

打开浏览器，访问：
1
https://Alansws.github.io
（请用你的 GitHub 用户名替换 Alansws）

2. 日常写作与管理

2.1 新建文章

在 personal-blog 目录下，运行：

1	hexo new post "你的文章标题"

这会在 source/_posts/ 目录下生成一个 Markdown 文件。
用你喜欢的编辑器（如 VSCode、Typora）编辑这个文件，撰写内容。

2.2 新建页面（如“关于我”、“友链”等）

1	hexo new page about

会在 source/about/index.md 生成页面文件。

2.3 本地预览

在 personal-blog 目录下运行：

1	hexo server

浏览器访问 http://localhost:4000
实时预览你的博客效果，修改内容后刷新即可看到变化。

2.4 发布到线上

每次写完文章或修改内容后，执行：

1	hexo clean && hexo generate && hexo deploy

这样你的博客就会自动同步到 GitHub Pages，几分钟后线上即可访问到最新内容。

3. 文章管理

所有文章都在 source/_posts/ 目录下，直接用 Markdown 编辑即可。
你可以自由添加、修改、删除文章文件。

4. 主题和功能扩展

想更换主题、调整样式、添加新功能（如统计、SEO、自定义菜单等），只需修改配置文件或安装插件即可。
NexT 主题文档：https://theme-next.js.org/

5. 评论系统

你的 Giscus 评论已配置好，读者可以直接在每篇文章下留言（需 GitHub 账号）。

6. 常见问题

内容没更新？
检查是否执行了 hexo clean && hexo generate && hexo deploy，并等待几分钟。
页面报错或样式异常？
检查 Markdown 格式、YAML 配置缩进，或清理浏览器缓存。

7. 备份与迁移

建议定期将整个 personal-blog 文件夹备份到本地或云盘。
换电脑时，只需拷贝此文件夹，安装 Node.js 和 Hexo 依赖即可继续写作。

如需更多高级玩法（自定义域名、SEO、自动化部署、数据统计等），随时告诉我，我可以继续为你详细指导！

祝你写作愉快，博客长虹！如有任何问题，随时来问我！

1	https://Alansws.github.io

1	hexo new post "你的文章标题"

1	hexo new page about

1	hexo server

1	hexo clean && hexo generate && hexo deploy

个人博客网站开发规划

1. 全局安装 Hexo-CLI

2. 初始化博客项目并进入目录

3. 安装项目依赖

在项目根目录（personal-blog）下执行

_config.yml

… (找到 theme 字段)

_config.yml

URL (非常重要，用于部署)

创建 “关于” 页面

创建第一篇文章

themes/next/_config.yml

Local Search

… (其他配置保持默认)

Comments

… (其他评论系统设为 false)

Giscus Configuration

你需要先在 https://giscus.app/zh-CN 上配置好你的仓库，然后将获得的信息填入下方

_config.yml (文件末尾)

清理旧文件、生成新网站文件、部署到GitHub

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

一、项目整体架构

二、开发关键节点与流程

三、注意事项

四、后续可扩展方向（可选）

步骤 1：环境初始化与项目创建

1.1 全局安装 Hexo-CLI

1.2 初始化博客项目

1.3 安装项目依赖

进度说明

原因分析

解决方案

1. 手动删除残留目录

2. 再次全局安装 Hexo-CLI

3. 如遇权限问题可加 sudo（仅限 Mac/Linux）

4. 检查是否有进程占用

步骤 2：安装并启用 NexT 主题

2.1 下载 NexT 主题

2.2 启用 NexT 主题

2.3 检查主题是否生效

原因分析

解决方案

1. 检查网络环境

2. 临时切换 Git 协议为 HTTP/1.1

3. 使用镜像源（推荐国内用户）

4. 检查代理设置

5. 多试几次

解决方案

1. 配置 Git 代理（以 HTTP 代理为例）

2. 代理软件设置

3. 使用镜像源（推荐）

4. 取消 Git 代理（如后续不用代理）

步骤 3：核心站点配置

3.1 修改站点配置信息

3.2 安装永久链接插件 abbrlink

3.3 检查与保存

步骤 4：创建基础内容

4.1 创建“关于”页面

4.2 创建第一篇文章

4.3 可选：本地预览

步骤 5：功能配置（评论 & 搜索）

5.1 安装本地搜索插件

5.2 配置 NexT 主题以启用本地搜索和 Giscus 评论

1. 启用本地搜索

2. 启用 Giscus 评论

3. 配置 Giscus

5.3 保存并检查

其他评论系统设为 false

你需要这样修改：

具体操作方法

示例（假设你叫 Alan，仓库名为 alan/alan.github.io）

步骤 6：配置部署

6.1 安装 Git 部署插件

6.2 配置 _config.yml 部署信息

6.3 检查仓库

6.4 保存并检查

1. Giscus 评论仓库与博客部署仓库可以不同

2. 你现在应该怎么做？

3. 部署配置怎么写？

4. 总结

6.2 配置 `_config.yml` 部署信息