duangxinBlog 项目总结

发表于 分类于

个人技术博客源码分析 | Hexo + NexT + Cloudflare Pages

一句话概括
duangxinBlog 是一个用于沉淀学习记录、论文阅读笔记、项目实践和阶段复盘的中文静态博客项目。项目用 Hexo 负责生成静态站点，用 NexT 提供博客主题和阅读体验，再通过 Cloudflare Pages 完成自动化构建与发布。

1. 项目定位

项目 说明
项目名称 duangxinBlog
项目类型 个人技术博客 / 静态站点源码
核心目标 把学习过程、阶段复盘和技术实践沉淀为可持续维护的博客内容。
维护方式 在本地仓库编辑 Markdown 文章，构建为静态文件，再通过托管平台发布。
当前状态 项目结构、主题配置、分类页面、标签页面、关于页面、学习计划页面和静态构建流程均已建立。

2. 使用的技术

层面 技术 / 配置 作用
运行环境 Node.js >= 20.19.0；.nvmrc 指向 Node 22 确保本地开发环境与部署环境的 Node 版本保持一致。
静态生成 Hexo 8.1.2 / hexo ^8.0.0 将 Markdown 文章、页面、模板和资源生成静态站点文件。
主题系统 hexo-theme-next ^8.27.0，NexT Pisces 方案 提供博客布局、菜单、归档、侧栏、文章目录、深色模式等界面能力。
内容格式 Markdown + YAML Front Matter 通过文本文件维护文章正文，并用 front matter 管理标题、日期、分类和标签。
渲染依赖 hexo-renderer-marked、EJS、Stylus、highlight.js 分别处理 Markdown、模板、样式和代码高亮。
生成插件 archive、category、index、tag、feed generators 生成首页分页、归档页、分类页、标签页和订阅源。
部署平台 Cloudflare Pages 监听主分支变更，执行构建命令，并把 public/ 目录发布为静态网站。
依赖维护 package-lock.json + Dependabot npm daily 锁定依赖版本，同时跟踪 npm 依赖更新。

3. 已实现功能

3.1 内容发布能力

  • 支持用 Markdown 编写文章，正式文章统一放在 source/_posts/。

  • 支持文章标题、发布时间、分类、标签等元信息管理。

  • 支持首页分页、文章详情页、归档页、分类页和标签页自动生成。

  • 支持 Atom 订阅源生成，方便读者订阅后续更新。

  • 构建输出统一进入 public/，便于静态托管平台发布。

3.2 站点阅读体验

  • 使用 NexT 的 Pisces 布局，整体结构适合个人技术博客和长文阅读。

  • 顶部菜单包含首页、归档、分类、标签、关于和学习计划。

  • 侧栏保持显示，并开启文章目录，方便阅读长文时快速跳转。

  • 开启深色模式、返回顶部、文章创建/更新时间、分类元信息和代码高亮行号。

  • 外部链接默认在新标签页打开，降低读者跳出当前文章的打断感。

3.3 分类与内容组织

分类 用途 维护建议
文章阅读 用于论文阅读、技术文章阅读和可复用的阅读笔记。 适合放结构化阅读记录，文章标题和标签要尽量清楚。
笔记 用于课程学习、工具使用、概念理解、项目过程记录。 适合沉淀学习过程中的阶段性理解和实践经验。
杂记 用于个人经历、阶段复盘，以及暂时不适合归入前两类的内容。 保持数量可控，后续如果某类内容变多，再拆分为更明确的分类。

当前文章仍统一放在 source/_posts/。项目更推荐用分类、标签和文件名前缀管理内容，而不是频繁移动已发布文章路径；如果未来确实要按目录拆分文章，应先固定 permalink，避免已发布链接发生变化。

3.4 附件管理

  • 图片、PDF、压缩包等附件统一放在 source/uploads/。

  • 文章中使用 /uploads/文件名 的方式引用附件。

  • post_asset_folder 已关闭，新建文章时不会再自动生成每篇文章同名的附件文件夹。

  • 构建后上传资源会输出到 public/uploads/，与文章中的引用路径对应。

4. 搭建过程说明

4.1 初始化与依赖准备

  1. 准备 Node.js 环境，并用 .nvmrc 约定 Node 22，避免本地和部署平台版本不一致。

  2. 安装 Hexo 及相关依赖，包括 Hexo 本体、NexT 主题、Markdown 渲染器、样式渲染器、代码高亮和各类页面生成插件。

  3. 在 package.json 中定义常用脚本：npm run server 用于本地预览，npm run build 用于生成静态文件，npm run clean 用于清理生成结果，npm run deploy 保留给 Hexo 部署命令。

  4. 通过 package-lock.json 锁定依赖版本，降低不同机器安装依赖时出现版本漂移的概率。

4.2 Hexo 站点配置

  • 在 _config.yml 中配置站点名称、副标题、描述、关键词、作者、语言和时区。

  • 设置 source_dir 为 source、public_dir 为 public，使源码内容和构建输出边界清晰。

  • 设置文章固定链接格式，保证文章路径可读、可追踪。

  • 配置首页分页、默认分类、日期格式、代码高亮、订阅源和主题名称。

  • 关闭 post_asset_folder，配合 source/uploads/ 形成统一附件管理规则。

4.3 NexT 主题配置

  • 在 _config.next.yml 中使用 Alternate Theme Config 管理主题，避免直接改动主题包造成升级冲突。

  • 选择 Pisces 布局，并开启深色模式，让页面适合长时间阅读。

  • 配置菜单项、侧栏、文章目录、文章元信息、返回顶部、动效和代码块样式。

  • 保留评论、搜索、统计、图片放大、懒加载等扩展项为关闭状态，当前阶段优先保证博客结构和内容发布稳定。

  • 配置社交入口和版权许可，但文档中不展示任何具体站点 URL。

4.4 内容目录与页面建立

  • source/_posts/ 用于正式文章，source/about/ 用于关于页，source/study-plan/ 用于学习计划页。

  • source/categories/ 和 source/tags/ 用于分类、标签入口页面。

  • scaffolds/ 保留 Hexo 新建页面和文章时使用的模板。

  • themes/ 目录只保留占位文件，实际主题通过 npm 依赖维护，便于依赖管理和升级。

5. 后续更新文章与部署流程

5.1 写文章

  1. 在 source/_posts/ 新建 Markdown 文件，文件名建议使用清晰的英文或拼音前缀，便于后续检索和排序。

  2. 在文件顶部写 front matter，至少包含 title、date、categories、tags。分类优先从“文章阅读”“笔记”“杂记”中选择。

  3. 正文按标题层级组织，长文建议使用二级、三级标题，让 NexT 的文章目录自动生成可用导航。

  4. 如果需要插入图片或附件，先把文件放入 source/uploads/，再在正文中用 /uploads/文件名 引用。

5.2 本地检查

  1. 运行 npm run server，在本地预览文章页面、分类页和标签页。

  2. 重点检查标题、日期、分类、标签、图片路径、代码块和目录跳转是否正常。

  3. 运行 npm run build，确认 Hexo 可以成功生成 public/。

  4. 如修改了附件，检查 public/uploads/ 是否出现对应文件。

  5. 运行 git status，确认改动范围只包含本次要发布的文章、附件或配置。

5.3 提交与发布

  1. 将本次修改加入 Git 暂存区，通常包括 source/_posts/、source/uploads/、必要的配置文件或 README。

  2. 提交时使用能说明内容的 commit message，例如“add new reading note”或“update blog writing guide”。

  3. 推送到 main 分支后，Cloudflare Pages 会按配置自动执行 npm run build。

  4. Cloudflare Pages 的构建目录应保持为 public，Node 版本使用 22 或至少 20.19.0+。

  5. 构建成功后，静态站点会自动发布；如果构建失败，优先检查 Node 版本、依赖安装、front matter 格式和资源路径。

5.4 发布后的维护规则

  • 已经发布过的文章不要随意移动路径；需要调整目录结构时，先固定 permalink。

  • 附件继续统一放入 source/uploads/，不要恢复每篇文章单独附件文件夹的旧流程。

  • 文章变多后，优先通过分类、标签、文件名前缀和学习计划页来增强导航。

  • 每次发布前至少跑一次 npm run build，这是最小但很关键的质量检查。

  • 当文章数量明显增加后，可以再启用本地搜索、图片懒加载、图片放大或阅读进度条等增强功能。

6. 项目结构说明

项目 说明
package.json 定义依赖、Node 版本要求和 build/clean/deploy/server 脚本。
_config.yml Hexo 站点级配置，负责站点信息、目录、文章生成、固定链接、订阅源和主题入口。
_config.next.yml NexT 主题配置，负责布局、菜单、侧栏、文章元信息和扩展功能开关。
source/_posts/ 文章 Markdown 源文件目录。
source/uploads/ 统一附件目录。
source/about/、source/study-plan/ 独立页面内容。
scaffolds/ Hexo 新建文章和页面时使用的模板。
public/ Hexo 构建输出目录，用于静态托管发布，不作为主要源码维护。

7. 后续优化建议

  • 启用本地搜索：文章数量增加后，可以安装并配置本地搜索数据库插件，再在 NexT 中打开 local_search。

  • 完善写作模板：为“文章阅读”“笔记”“杂记”分别准备 front matter 和正文结构模板。

  • 建立发布清单：把本地预览、构建、附件检查、git status、推送后的构建检查写成固定 checklist。

  • 增强阅读体验：根据需要逐步开启图片懒加载、图片放大、阅读进度条等功能。

  • 维护分类克制：短期内保持三类内容体系，等内容量足够后再拆分新分类。

资料依据：当前仓库文件 package.json、README.md、_config.yml、_config.next.yml、source/_posts/、source/uploads/、.nvmrc、.github/dependabot.yml，以及 2026-06-02 本地 npm run build 验证结果。