全局配置

本页梳理博客的全局配置：站点信息、URL 与永久链接、主题基础（Logo/Favicon）、Banner 背景、CDN 机制。这是整个博客的地基，其他配置篇都建立在它之上。

配置分两层：站点配置 _config.yml（Hexo 核心 + 插件）与主题配置（布局/外观/交互）。本项目 CI 构建时主题配置文件会被 userConfig/_config.tmp.yml 模板覆盖，改主题配置请改模板（详见「安装与主题配置」篇）。本页除标注"根配置"外均为主题配置。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

1. 站点信息

用途：站点名称、副标题、描述、作者等基础信息，影响标题栏、SEO 与全站文字。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：浏览器标签页显示「夜法之书」，页头显示站点名与副标题，搜索结果与分享卡片使用 description。

对应配置（根配置 _config.yml）：

title: 夜法之书
subtitle: '深度思考，深入生活！所有文章均持续滚动更新！'
description: '~软件驱动世界~个人独立技术博客，关于Linux,开源，Nas，Docker，嵌入式，理财，健身等主题！'
author: 夜法之书
language: zh-CN
timezone: Asia/Shanghai

1.2 常用选项

① 站点标题与副标题

效果：title 出现在标签页与页头；subtitle 出现在 Banner 打字机与页头下方。

对应配置：

title: 夜法之书
subtitle: '深度思考，深入生活！'

② 站点描述

效果：SEO meta description 与 RSS 描述使用这段文字。

对应配置：

description: '个人独立技术博客'

③ 作者兜底

效果：文章 front-matter 没写 author 时，页面作者显示这里；写了则以 front-matter 为准。

对应配置：

author: 夜法之书

④ 语言与时区

效果：language 决定 html lang 与日期本地化；timezone 决定文章日期按哪个时区渲染。

对应配置：

language: zh-CN
timezone: Asia/Shanghai

1.3 全部可调项

1.4 边界与冲突

• author 是文章的兜底作者——文章 front-matter 未写 author 时用它。
• language 影响站点 html lang 属性与日期本地化。
• timezone 必须与目标读者时区一致，否则文章日期会偏移。
• 这些键在根配置，不在 userConfig/_config.tmp.yml 的覆盖范围内。

1.5 小结

• 最小可用：title + author + language
• SEO：认真写 description
• 日期偏移：先查 timezone
• 改了不生效：改的是根 _config.yml 吗？

2. URL 与永久链接

用途：站点根 URL 与文章链接格式。本博客使用 abbrlink（CRC32 + hex）生成短链接，文章发布后永久不变。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：文章链接形如 https://blog.17lai.site/posts/8f9792ab/，短且与标题无关；改标题不会改变链接。

对应配置（根配置 _config.yml）：

url: https://blog.17lai.site
permalink: posts/:abbrlink/

abbrlink:
  alg: crc32
  rep: hex

2.2 常用选项

① 站点根 URL

效果：canonical、sitemap、RSS 里的绝对链接都以它为前缀；填错会导致全站外链指向错误域名。

对应配置：

url: https://blog.17lai.site

② 链接格式

效果：文章 URL 变成 /posts/<abbrlink>/；改格式会让所有旧链接失效。

对应配置：

permalink: posts/:abbrlink/

③ 哈希算法与进制

效果：crc32 + hex 生成 8 位十六进制短链；换算法只影响新文章，旧 abbrlink 已写入 front-matter。

对应配置：

abbrlink:
  alg: crc32
  rep: hex

④ 草稿是否生成短链

效果：drafts: true 时草稿也分配 abbrlink；默认 false，草稿发布时才生成。

对应配置：

abbrlink:
  drafts: true

2.3 全部可调项

2.4 边界与冲突

• writeback: false（2026-09-22 起）表示插件不回写源文件 —— 关闭原因是常驻 hexo server 若在编辑窗口期读到空文件，插件会用残缺对象覆盖源文件（详见 docs/EXPERIENCE.md §55）。
• abbrlink 由插件在首次生成时写入各篇文章的 front-matter，此后固定，改名文章不会破坏旧链接。
• url 是所有绝对链接（canonical、sitemap、RSS）的基准，生产环境必须与部署域名一致。
• force: true 会重算全部短链，等于让所有已发布链接失效，除非明确要迁移。

2.5 小结

• 最小可用：url + permalink
• 短链：alg: crc32 + rep: hex
• 别开 force：会废掉旧链接
• 别开 writeback：常驻 server 有覆盖源文件风险

3. 主题基础：Logo 与 Favicon

用途：站点图标与页头 Logo，目前共用同一张图。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：浏览器标签页显示自定义图标；页头左侧显示同一张图作为 Logo。

对应配置（主题配置）：

favicon: /favicon.webp
logo: /favicon.webp

3.2 常用选项

① 换站点图标

效果：标签页图标变化（支持 webp/png/ico）。

对应配置：

favicon: /my-icon.png

② 换页头 Logo

效果：导航栏左侧图形变化；建议与 favicon 分开成横版 Logo。

对应配置：

logo: /my-logo.webp

③ 繁简转换默认方向

效果：中文繁简转换功能默认显示简体或繁体。

对应配置：

zhDefaultEncoding: 2

3.3 全部可调项

3.4 边界与冲突

• 图片放 source/ 根目录即可被静态化。
• zhDefaultEncoding 是"中文繁简转换"功能的默认方向，与 preference.translate 配合（见「多语言与 Wiki 系统」篇）。
• 替换图标后浏览器可能缓存旧 favicon，需要强制刷新。

3.5 小结

• 最小可用：favicon + logo
• 品牌感：Logo 与 favicon 分开做
• 图标不更新：清浏览器缓存

4. Banner 背景

用途：所有页面的头图 Banner。可每日轮换、随机取图、滚动视差，并叠加打字机副标题。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

效果：页面顶部出现大幅背景图，图上副标题逐字打出来并带闪烁光标。

对应配置（主题配置）：

banner:
  enable: true
  random: true

4.2 常用选项

① 每日轮换 / 固定图

效果：enable: true 时每天换一张；false 时固定用 /medias_webp/banner/0.webp。

对应配置：

banner:
  enable: false

② 随机取图

效果：从 featureImages 中随机挑图，配合 enable: true 形成"每日一图"。

对应配置：

banner:
  random: true

③ 视差滚动

效果：向下滚动时背景图与内容以不同速度移动，产生纵深。

对应配置：

banner:
  parallax: true

④ 移动端防过度裁剪

效果：限制图片最小宽高比，竖屏下不会把图裁成一条；0 关闭限制。

对应配置：

banner:
  width_height_ratio: 1.0

⑤ 打字机副标题

效果：副标题逐字出现、可循环、可带光标。

对应配置：

banner:
  typed:
    enable: true
    loop: false
    showCursor: true
    cursorChar: "_"

⑥ 打字速度

效果：typeSpeed 越大打字越慢，backSpeed 越大删除越快，startDelay 控制开始前停顿。

对应配置：

banner:
  typed:
    startDelay: 100
    typeSpeed: 80
    backSpeed: 50

4.3 全部可调项

4.4 边界与冲突

• random: true 时从 featureimages 中随机取图，配合 enable: true 实现"每日一图"。
• typed 打字机渲染的是副标题（站点 subtitle 或首页 index.slogan.text，见「导航菜单与首页」篇）。
• 开启 background.image.random 时不显示文章 banner（见「文章页配置」§1）。

4.5 小结

• 最小可用：enable: true
• 固定图：enable: false
• 想有动效：parallax + typed
• 竖屏裁图：调 width_height_ratio

5. CDN 配置机制

用途：全站静态资源（JS/CSS/图片）走 CDN 加速。本项目用 jsDelivr + 占位符注入：模板中写 {cdnPathVersion} 等占位符，CI 构建时统一替换成真实 CDN 地址。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：构建后页面里的 JS/CSS 链接指向 jsDelivr 的带版本路径，浏览器从 CDN 加载；本地直接 hexo generate 时仍保留占位符（未替换）。

对应配置（主题配置）：

jsDelivr:
  url: {cdnPathVersion}

cdn:
  url: "{cdnUrl}"
  mediaUrl: "{mediaUrl}"
  resUrl: "{resUrl}"

5.2 常用选项

① 带版本号的 CDN 路径

效果：资源 URL 带上 @1.1 这类版本号，发版后浏览器拉新文件。

对应配置：

jsDelivr:
  url: {cdnPathVersion}

② latest 路径

效果：始终指向最新版本（不推荐生产使用，缓存不可控）。当前被注释、未启用。

对应配置：

jsDelivr:
  latesturl: #{cdnPathLatest}

③ 三类资源域名

效果：JS/CSS、图片/媒体、其他资源分别从各自域名加载。

对应配置：

cdn:
  url: "{cdnUrl}"
  mediaUrl: "{mediaUrl}"
  resUrl: "{resUrl}"

5.3 全部可调项

占位符与构建时替换（由 userConfig/_config.tmp.yml + tools/cicd.sh 的 sed 完成）：

5.4 边界与冲突

• 本页写配置时不需要关心占位符——保持 {xxx} 原样即可，CI 会处理。
• 发布时机：改 JS/CSS 后需 tools/cicd.sh -r "特性" 递增版本号（tools/.VERSION），否则浏览器/PWA 缓存旧版；仅改内容用 -c 或 -d。
• 直接 hexo generate 不会替换占位符，资源会 404；必须走 CI 脚本。

5.5 小结

• 最小可用：保持模板占位符不动
• 改资源：必须 -r 递增版本
• 别用 latest：生产缓存不可控
• 本地 404：没走 CI 注入

6. 站点运行时间（time）

用途：页脚显示"本站已运行 N 年 N 天"，从设定的建站时间起算。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

6.1 如何启用

效果：页脚出现「本站已运行 6 年 3 个月 12 天」，数字随时间自动增长。

对应配置（主题配置）：

time:
  enable: true
  year: 2020
  month: 06
  date: 28
  hour: 00
  minute: 00
  second: 00

6.2 常用选项

① 改建站时间

效果：运行时长从新时间重新计算。

对应配置：

time:
  year: 2021
  month: 01
  date: 01

② 关闭运行时间

效果：页脚不再显示运行时长。

对应配置：

time:
  enable: false

6.3 全部可调项

6.4 边界与冲突

• 时间设为博客首次上线日期即可，页脚自动计算并显示运行时长。
• month 建议保留前导 0（如 06），避免 YAML 解析歧义。

6.5 小结

• 最小可用：enable + 年月日
• 刚建站：填今天
• 不想显示：enable: false

7. Fork Me 图标（githubLink）

用途：页头右上角显示 “Fork Me on GitHub” 角标，链接到你的仓库。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

7.1 如何启用

效果：页面右上角出现斜挂的 “Fork Me on GitHub” 丝带，点击跳转仓库。

对应配置（主题配置）：

githubLink:
  enable: true
  url: https://github.com/appotry/hexo
  title: Fork Me

7.2 常用选项

① 改仓库地址

效果：点击角标跳到你的仓库。

对应配置：

githubLink:
  url: https://github.com/you/your-repo

② 改文案

效果：丝带上的文字变化。

对应配置：

githubLink:
  title: 查看源码

7.3 全部可调项

7.4 边界与冲突

• enable: true 时在 header 显示角标；url 指向你的 GitHub 仓库。
• 与导航菜单里的 GitHub 链接是两处独立入口，可只留其一。

7.5 小结

• 最小可用：enable + url
• 想低调：保持默认关闭
• 文案本地化：改 title

8. 主题颜色（color）

用途：全站配色——PWA 主题色、背景、导航栏、文字等，明暗两套。其他未覆盖的颜色用自定义 CSS 解决。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

8.1 如何启用

效果：全站背景、导航栏、正文与次级文字按配置着色；切到暗色模式时自动换用 *_dark 值。

对应配置（主题配置）：

color:
  theme_color: "#7e9fc4"
  body_bg_color: "#eee"
  body_bg_color_dark: "#181c27"

8.2 常用选项

① 背景色（明/暗）

效果：页面底色变化，卡片浮在其上。

对应配置：

color:
  body_bg_color: "#f5f5f5"
  body_bg_color_dark: "#181c27"

② 导航栏颜色

效果：顶部菜单背景与文字颜色变化。

对应配置：

color:
  navbar_bg_color: "rgba(255, 255, 255, 0.8)"
  navbar_text_color: "#f8f8f8"

③ 正文与次级文字

效果：正文变深/变浅，摘要等次级文字用 sec_text_color。

对应配置：

color:
  text_color: "#3c4858"
  sec_text_color: "#718096"

④ PWA 主题色

效果：手机浏览器地址栏与 PWA 启动画面使用该颜色（manifest + theme-color meta）。

对应配置：

color:
  theme_color: "#7e9fc4"

8.3 全部可调项

8.4 边界与冲突

• 每个颜色键都有对应的 *_dark 暗色值，改色时两套一起调。
• 配色灵感可参考 LOL Colors。
• 颜色最终由 _variables/base.styl → :root CSS 变量 → color-schema.styl 三层传递，直接写 .css 会被构建覆盖。

8.5 小结

• 最小可用：只改 theme_color
• 整体换肤：明暗成对改
• 别只改一半：漏了 *_dark 暗色模式会突兀
• 改样式走 .styl：不要动编译产物

9. 字体（font）

用途：全站正文字号、字体族、字间距与代码字号。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

9.1 如何启用

效果：正文按指定字号与字体族渲染，代码块字号按正文比例缩放。

对应配置（主题配置）：

font:
  font_size: 16px
  font_family:
  letter_spacing: 0.02em
  code_font_size: 85%

9.2 常用选项

① 正文字号

效果：全站正文变大/变小，行高按比例跟随。

对应配置：

font:
  font_size: 18px

② 字体族

效果：留空用主题默认字体栈；填字体名则优先使用该字体（需用户本机或已加载）。

对应配置：

font:
  font_family: "Noto Sans SC"

③ 字间距

效果：正文汉字间距变化，中文排版更松/更紧。

对应配置：

font:
  letter_spacing: 0.05em

④ 代码字号

效果：代码块文字按正文百分比缩放，85% 比正文略小。

对应配置：

font:
  code_font_size: 90%

9.3 全部可调项

9.4 边界与冲突

• font_family 留空时使用主题默认字体栈；代码块字号按正文百分比缩放。
• 自定义字体需自行加载字体文件（主题不自动引入网络字体）。
• 字号与 §10 design.font_size_* 是两套：font.font_size 是正文基准，design.font_size_* 是组件字号刻度。

9.5 小结

• 最小可用：只改 font_size
• 中文更松：调 letter_spacing
• 代码太小：code_font_size: 90%
• 字体不生效：用户机器没有该字体

10. 设计令牌（design）

用途：圆角/阴影/过渡/渐变/间距/字号刻度的设计令牌，由 color-schema.styl 映射为 CSS 变量，全站组件统一引用。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

10.1 如何启用

效果：卡片圆角、悬浮阴影、按钮渐变、组件间距与字号全部按令牌渲染；改一个令牌，全站同类元素一起变。

对应配置（主题配置）：

design:
  radius_md: 8px
  shadow_md: "0 2px 5px 0 rgba(0,0,0,0.16)"
  transition_normal: 0.3s
  space_4: 16px
  font_size_md: 1.125rem

10.2 常用选项

① 圆角

效果：radius_sm 影响按钮/小标签，radius_md 影响卡片，radius_lg 影响弹窗，radius_pill 做胶囊，radius_full 做圆形。

对应配置：

design:
  radius_sm: 3px
  radius_md: 8px
  radius_lg: 12px
  radius_pill: 999px
  radius_full: 50%

② 阴影

效果：shadow_sm 悬浮微阴影，shadow_md 卡片默认，shadow_lg 卡片 hover，shadow_xl 弹窗/浮层；暗色用 *_dark。

对应配置：

design:
  shadow_sm: "0 1px 3px 0 rgba(0,0,0,0.12)"
  shadow_md: "0 2px 5px 0 rgba(0,0,0,0.16)"
  shadow_md_dark: "0 2px 5px 0 rgba(0,0,0,0.45)"

③ 过渡时长

效果：fast 用于悬停反馈，normal 用于面板/弹窗展开。

对应配置：

design:
  transition_fast: 0.2s
  transition_normal: 0.3s

④ 渐变

效果：gradient_primary 用于导航/按钮，gradient_accent 用于卡片装饰。

对应配置：

design:
  gradient_primary: "linear-gradient(to right, #4facfe, #00f2fe)"
  gradient_accent: "linear-gradient(135deg, #667eea, #764ba2)"

⑤ 间距与字号刻度

效果：组件内边距按 space_* 取值；字号按 font_size_* 取值，并随 --font-scale 整体缩放。

对应配置：

design:
  space_1: 4px
  space_4: 16px
  font_size_md: 1.125rem
  font_size_2xl: 2rem

10.3 全部可调项

10.4 边界与冲突

• 这是主题的设计系统层——组件统一引用这些令牌，改一处全局生效。
• 调整时保持刻度体系（圆角/阴影/间距各自成梯级），不要只改单个值破坏一致性。
• 字号为 rem 制，随根元素 --font-scale 变量整体缩放（用户可调字号时全站等比变化），不要改成 px 固定值。
• 颜色不在此段：颜色走 §8 color 段。

10.5 小结

• 最小可用：只调 radius_md / shadow_md
• 换风格：整组改，保持梯级
• 字号别改 px：保持 rem
• 颜色去 §8：这里只管圆角/阴影/间距

11. 网页访问统计（web_analytics）

用途：全站访问统计，支持百度统计、Google Analytics 4 与自建 umami 三套，可同时启用。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

11.1 如何启用

效果：页面加载后向统计服务上报 PV/UV；页脚可显示总访问量与总人次。

对应配置（主题配置）：

web_analytics:
  enable: true
  umami:
    enable: true
    src: https://ana.17lai.site/script.js
    api_server: https://ana.17lai.site
    website_id: "your-website-id"

11.2 常用选项

① 关闭统计

效果：不再注入任何统计脚本。

对应配置：

web_analytics:
  enable: false

② 遵循 DNT

效果：浏览器开启"请勿追踪"的访客不被统计。

对应配置：

web_analytics:
  follow_dnt: true

③ 百度统计

效果：数据进入百度统计后台。

对应配置：

web_analytics:
  baidu:
    enable: true
    id: your-baidu-id

④ Google Analytics 4

效果：数据进入 GA4 媒体资源。

对应配置：

web_analytics:
  google:
    enable: true
    measurement_id: 'G-XXXXXXXXXX'

⑤ umami 页脚 PV/UV

效果：页脚显示总访问量与总人次（配合 footer.statistics）。

对应配置：

web_analytics:
  umami:
    totalTraffic: true
    totalNumberOfvisitors: true

⑥ 统计起始时间与 API

效果：只统计 start_time 之后的数据；api_server 与 website_id 决定从哪个实例取数。

对应配置：

web_analytics:
  umami:
    start_time: '2023-01-01'
    api_server: https://ana.17lai.site
    website_id: "your-website-id"

11.3 全部可调项

11.4 边界与冲突

• umami 的 totalTraffic/totalNumberOfvisitors 对应页脚 PV/UV 显示（配合 footer.statistics）。
• start_time 填 umami 站点创建时间，必须用引号包裹，否则 YAML 解析为 Date 对象后 JSON.stringify 会变成 {}。
• token 需在 umami 后台新建 viewOnly 用户获取。
• 三套统计可同时启用，但会重复上报；一般只留一套。

11.5 小结

• 最小可用：enable + umami 的 src / website_id
• 页脚 PV/UV：totalTraffic + totalNumberOfvisitors
• start_time 一定加引号
• 别三套全开：重复上报

附：全局配置速查表

阅读顺序建议：先配 §1–§3（站点身份与图标），再配 §4（Banner 观感），然后 §6–§10（页脚、配色、字体、令牌），最后接 §11 统计。§5 CDN 只在发版排障时看——平时保持占位符不动。