环境要求

项目 建议版本
Node.js 18 或更高（推荐 20+）
Hexo 6.x / 7.x
包管理器 npm / pnpm / yarn 均可

检查当前环境：

1
2
node -v
npx hexo version

安装主题

把主题文件夹放进站点的 themes/ 目录，然后修改站点根目录的 _config.yml：

1
2
# --- 主题 ---
theme: echo

如果主题目录名不是 echo，theme: 的值要跟目录名一致。

接着安装必要依赖（主题用到了 hexo-pagination 做分页）：

1
npm install hexo-pagination --save

常用命令

1
2
3
4
5
6
7
8
9
10
11
# 本地预览，默认 http://localhost:4000
npx hexo server

# 指定端口（端口被占用时很有用）
npx hexo server -p 4000

# 清缓存后重新生成
npx hexo clean && npx hexo generate

# 生成并部署
npx hexo clean && npx hexo generate --deploy

改完主题文件后，如果是 hexo server 正在运行，通常会自动热更新；
改了 _config.yml 或 scripts/ 下的生成器，必须重启 server 才会生效。

站点配置：资源板块

资源库的类型、路径和分页在站点 _config.yml 里配置（不是主题配置里）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# --- 资源板块 ---
resources:
  path: resources          # 访问路径：/resources/
  per_page: 12             # 每页显示多少个资源
  types:                   # 资源类型，决定筛选条和图标
    - key: movie
      name: 影视资源
      icon: film
    - key: game
      name: 游戏资源
      icon: gamepad
    - key: mod
      name: 游戏 MOD
      icon: puzzle
    - key: translation
      name: MOD 汉化
      icon: language
    - key: software
      name: 软件工具
      icon: app
    - key: other
      name: 其他资源
      icon: box

几个要点：

  • key 要和文章 front-matter 里 resource.type 的值一致，否则会被归到「其他资源」。
  • icon 取自主题内置图标集（见第四篇的图标清单）。
  • per_page 同时作用于资源库和文章列表。

站点配置：文章板块

1
2
3
4
5
# --- 文章板块 ---
# 只收录「普通文章」（不含 resource.enable 的资源帖）
articles:
  path: articles
  per_page: 12

站点配置：固定链接

主题默认按「分类 / 年 / 月 / 标题」组织链接，这样资源帖的 URL 天然带分类信息：

1
2
3
4
permalink: :category/:year/:month/:title/
pretty_urls:
  trailing_index: true
  trailing_html: true

改 permalink 会导致已有链接全部失效，如果站点已经上线过，建议先做跳转再改。

主题配置总览

主题自己的配置在 themes/echo/_config.yml，该文件已按功能分好 14 个区块、
每一项都带中文注释（含可填值与「站点配置可覆盖」的说明），可以直接当参考手册用。

区块 作用 详解位置
一、外观与配色 配色模式、主色、派生变量、圆角 03 篇
二、三栏布局尺寸 总宽、栏距、中栏宽度、侧栏宽度 03 篇
三、站点图标 标签栏 / 收藏夹 / 导航栏品牌图标 05 篇
四、header 内页顶部横幅 03 篇
五、hero 首页顶部大图与按钮 03 篇
六、menu 导航菜单（单行语法） 05 篇
七、index 首页内容区（Hero 关闭时才显示） 03 篇
八、rail 左右侧栏开关与宽度 03 篇
九、左栏组件 profile / music / category / tags 06 篇
十、右栏组件 stats / toc / calendar / siteinfo 06 篇
十一、resource 资源字段、提取码、网盘配色 04 篇
十二、post 文章页目录、版权、上下篇、简介 05 篇
十三、comments giscus 评论 06 篇
十四、footer 页脚年份、Powered by、备案 06 篇

覆盖优先级

配置读取一律按这个顺序，前者覆盖后者：

1
站点 _config.yml  >  主题 _config.yml  >  代码内置默认值

所以想换成自己的图片、宽度、配色，优先写到站点 _config.yml 里（同名同层级即可），
不用动主题文件 —— 这样更新主题时不会冲突。目前支持站点覆盖的常用项：

站点配置项 覆盖主题的
favicon favicon，同时用作导航栏品牌图标
author / description 名片的 name / bio
title / subtitle 导航栏品牌文字
url 站点信息里的 domain
resources.path / resources.types 资源库路径与类型图标
theme: echo 主题目录名

首次运行检查清单

改完配置后，按这个清单过一遍：

  • theme: echo 已设置
  • resources.types 里的 key 与文章 resource.type 对应
  • 站点 url 改成你自己的域名（影响 RSS 与站点地图）
  • 站点 favicon 换成自己的图标
  • 主题 profile.avatar、社交链接换成自己的
  • footer.since 改成建站年份
  • stats.since 与建站日期一致
  • comments.giscus.repo 换成你自己的公开仓库
  • hero.image 换成 1920×1080 以上的横向图

下一篇

下一篇讲三栏布局、宽度调节、深色模式与首页大图。