hexo 学习►其它

hexo 学习 0034:hexo 贡献指南

开源项目的生命力源于社区的贡献。无论你是一位经验丰富的开发者，还是一位刚入门的技术爱好者，都可以为 Hexo 生态添砖加瓦。本文将详细拆解参与 Hexo 开发的完整流程，涵盖代码贡献、文档更新、翻译工作以及问题报告的核心规范。

一、核心概念辨析：Fork 与 Clone

在开始之前，我们需要明确两个在 Git 工作流中极易混淆的概念：Fork 和 Clone。

  • Fork（分叉）：

    • 比喻：就像是在图书馆里复印了一本书的完整副本带回家。这本书原本属于图书馆（原始仓库），现在你家里也有了一本完全一样的书（你的远程仓库），你可以随意在上面涂写修改，而不会影响图书馆的原版。
    • 操作位置：在 GitHub 网页界面上进行。
    • 作用：将别人的项目复制到你的 GitHub 账号下，获得独立的修改权限。

  • Clone（克隆）：

    • 比喻：把你家里那本复印的书，再抄写一份放到你的书桌上，以便你随时阅读和编辑。
    • 操作位置：在本地电脑终端（命令行）进行。
    • 作用：将远程仓库（通常是你 Fork 后的仓库）的代码下载到本地计算机。

工作流逻辑：先在网上 Fork 得到自己的仓库，再在本地 Clone 下来进行开发。

二、代码开发贡献流程

如果你希望修复 Hexo 核心的 Bug 或开发新功能，请遵循以下严格的工作流。

1. 开发前准备

在动手写代码之前，必须遵守社区的行为准则和代码规范，这相当于加入团队前的“入职培训”。

  • 行为准则：务必阅读 《贡献者行为准则》，确保言行符合社区规范。
  • 代码风格：
    • 遵循 Google JavaScript 代码风格。
    • 缩进：必须使用 2 个空格。不要使用 Tab 键。
    • 逗号：不要把逗号放在行首（即使用行尾逗号风格）。
  • 代码检查：Hexo 使用专门的 ESLint 配置 来检查代码质量。你的代码必须能通过 ESLint 检查，否则无法被合并。

2. 环境搭建与工作流

第一步：Fork 仓库
访问 hexojs/hexo 页面，点击右上角的 “Fork” 按钮，将项目复制到你的 GitHub 账号下。

第二步：克隆与安装依赖
将你的 Fork 仓库克隆到本地，并安装所有必要的依赖包。注意，Hexo 使用了子模块，必须初始化。

命令示例：

1
2
3
4
5
# 将 <username> 替换为你的 GitHub 用户名
$ git clone https://github.com/<username>/hexo.git
$ cd hexo
$ npm install
$ git submodule update --init

参数与命令详解：

  • git clone <url>：下载仓库代码到本地当前目录。
  • cd hexo：进入项目根目录。
  • npm install：读取 package.json，安装项目运行所需的所有 Node.js 依赖包到 node_modules 文件夹。
  • git submodule update --init：关键步骤。Hexo 包含子模块（submodules），此命令用于下载和初始化这些子模块的内容。如果遗漏此步，测试或运行可能会失败。

第三步：创建功能分支
永远不要在 master 或 main 主分支上直接修改。创建一个新分支来隔离你的开发工作。

命令示例：

1
$ git checkout -b new_feature

参数详解：

  • checkout：切换分支的命令。
  • -b：表示 “create branch”，如果分支不存在则创建它，然后立即切换过去。
  • new_feature：你自定义的分支名称。建议使用有意义的名字，如 fix-yaml-bug 或 add-new-tag。

第四步：编写代码 (Start hacking)
在此阶段修改代码文件。

第五步：推送分支
将本地修改上传到你的 GitHub 远程仓库。

命令示例：

1
$ git push origin new_feature

参数详解：

  • push：上传命令。
  • origin：远程仓库的默认别名，指向你 Fork 的那个仓库。
  • new_feature：要推送的本地分支名。这会将本地分支关联并推送到远程同名分支。

第六步：发起合并申请 (Pull Request)

  1. 前往你 Fork 的 GitHub 仓库页面。
  2. 系统通常会提示你刚推送了分支，点击 “Compare & pull request”。
  3. 详细描述你的改动内容、修复的问题以及测试情况。
  4. 提交 PR，等待维护者审查。

3. 重要注意事项

  • 禁止修改版本号：不要手动修改 package.json 中的 version 字段。版本号由维护者在发布时统一管理。
  • 必须通过测试：只有测试通过的代码才会被批准。在提交 PR 前，必须在本地运行测试套件。

测试命令：

1
$ npm test

说明：该命令会运行项目配置的测试脚本（通常在 package.json 的 scripts.test 中定义），确保你的修改没有破坏现有功能。

三、文档更新贡献流程

Hexo 的文档也是开源的，托管在 hexojs/site 仓库。修正错别字、优化教程或补充说明都属于文档贡献。

1. 工作流

第一步：Fork 仓库
访问 hexojs/site 并点击 “Fork”。

第二步：克隆与安装
下载文档源码并安装依赖。如果你还没有安装 Hexo 命令行工具，需要先全局安装。

命令示例：

1
2
3
4
5
6
7
# 如果未安装 hexo-cli，先执行全局安装
$ npm install hexo-cli -g

# 克隆你的 Fork 仓库
$ git clone https://github.com/<username>/site.git
$ cd site
$ npm install

参数详解：

  • npm install hexo-cli -g：
    • -g：Global，表示全局安装。这样你可以在任何目录下使用 hexo 命令。
  • npm install：安装文档站点构建所需的主题和插件依赖。

第三步：预览修改
在本地启动服务器，实时预览文档修改效果。

命令示例：

1
$ hexo server

说明：启动本地开发服务器（默认端口 4000）。当你保存文件修改后，浏览器刷新即可看到最新效果。这是验证文档格式是否正确的最佳方式。

第四步：推送与 PR
确认无误后，按照代码贡献的流程（创建分支 -> 推送 -> 发起 Pull Request）提交你的文档更新。

四、翻译贡献指南

Hexo 使用 Crowdin 平台管理多语言翻译，这使得非技术人员也能轻松参与。

1. 参与现有语言翻译

你不需要懂 Git 命令。只需访问 Crowdin 项目页面，注册账号，选择你想要贡献的语言，即可在线翻译字符串并投票支持他人的翻译。

Crowdin Badge

2. 添加新语言

如果你想让 Hexo 支持一种全新的语言，需要配合开发人员完成以下步骤：

步骤 1：提交议题 (Issue)
在 Hexo 的 GitHub 仓库提交一个新的 Issue，告知社区你想添加某种语言。拥有 Crowdin 权限的管理员会在后台添加该语言配置。

步骤 2：在线翻译
语言在 Crowdin 上激活后，任何人都可以像上面描述的那样去贡献翻译内容。

步骤 3：配置语言列表
在文档仓库 hexojs/site 中，编辑 source/_data/language.yml 文件，将新语言添加到列表中。

配置示例 (source/_data/language.yml)：

1
2
3
4
en: English
zh-CN: 简体中文
# 新增一行，格式为 "代码: 显示名称"
es: Español

步骤 4：添加导航语言文件
将英文导航文件复制一份并重命名为新语言的代码（全小写）。

操作路径：

  • 源文件：themes/navy/languages/en.yml
  • 目标文件：themes/navy/languages/es.yml (以西班牙语为例)

你需要修改这个新文件中的导航菜单文本，使其匹配新语言。

五、如何正确报告问题 (Issue)

当你在使用 Hexo 遇到无法解决的问题时，请按以下步骤操作，这能极大提高问题被解决的效率。

1. 自助排查

在提问前，请先查阅官方 问题解答文档。很多常见问题（如 YAML 错误、端口占用等）已有标准答案。你也可以在 Google Group 搜索历史讨论。

2. 调试模式复现

如果文档中没有答案，你需要在 调试模式 下复现问题，以获取详细的错误日志。

命令示例：

1
2
3
$ hexo --debug generate
# 或者简写
$ hexo -d g

参数详解：

  • --debug / -d：开启调试模式。Hexo 会输出详尽的内部运行日志，包括加载了哪些插件、处理了哪些文件、在哪一步报错等。这对定位问题至关重要。

3. 提交 GitHub Issue

访问 Hexo GitHub Issues 提交新问题。

关键要求：

  • 遵循模板：GitHub 会自动加载 Issue 模板，请严格按照模板填空。
  • 提供调试信息：将你在调试模式下得到的完整错误日志粘贴进去。
  • 版本信息：注明你的 Hexo 版本、Node.js 版本以及操作系统信息。
  • 复现步骤：清晰描述如何操作能触发该错误。

六、其他贡献途径

除了核心代码和文档，你还可以为 Hexo 官方插件 生态系统做贡献。Hexo 拥有多个官方维护的插件仓库（如 hexo-server, hexo-deployer-git 等），它们同样欢迎 PR（合并请求）和 Issue（问题反馈）。流程与上述核心开发流程一致：Fork -> Clone -> 修改 -> 测试 -> PR。

通过参与这些环节，你不仅帮助了社区，也是深入理解 Hexo 架构的最佳学习方式。