用过某些博客框架的朋友经常会遇到这种尴尬：改个博客标题要在 _config.yml 里改一次，改个导航栏要去主题目录下的 theme.yml 再改一次，换个社交链接甚至还要翻进模板源码去手改 HTML。配置散落在三四个角落，不知道的还以为改博客配置是在玩解谜冒险游戏。
RustPress 将全站所有的元数据、作者信息、导航菜单与功能开关全部收拢在单一的 config.toml 中。并且在开发模式下，改动任何一个参数，本地热重载即刻生效。
本篇逐一拆解 config.toml 的每个配置小节，帮你快速理清每个控制点。
一、配置文件位置与加载优先级
RustPress 支持在两个位置读取配置文件：
- 根目录：
./config.toml（全局通用默认配置） - 源目录：
./source/config.toml（独立内容仓库或特殊覆盖模式）
当你执行 rustpress -m source serve 或 rustpress -m source build 时，系统会优先读取 source/config.toml；如果源目录下没有，则回退读取根目录下的 config.toml。
为什么把 config.toml 放在源码目录下？在软件开发中，我一直坚持目录自足的原则，所以优先把它放在了 source 目录下。
二、config.toml 完整配置速查
一份包含了所有功能字段的标准 config.toml 如下：
# ==============================================================================
# 1. 站点核心元数据 [site]
# ==============================================================================
[site]
name = "艺述论" # 网站主名称（展示于导航栏与浏览器标题）
description = "一花一世界，一树一菩提。" # 站点副标题、Slogan 及 SEO Meta 描述
author = "金石碼农" # 默认作者署名
logo = "/static/images/avatar.png" # 顶部导航栏 Logo 图片路径
favicon = "/static/images/favicon.ico" # 浏览器标签页 Favicon 图标
domain = "https://yishulun.com" # 生产环境正式域名（用于生成 RSS、Sitemap 与绝对路径）
base_url = "http://localhost:1111" # 当前编译的基础 URL（本地预览填 localhost，线上 CI/CD 填正式域名）
dev_domains = ["dev.yishulun.com", "localhost", "127.0.0.1", "0.0.0.0", "::1"] # 本地/测试域名（支持草稿展示与动态发布框）
icp_license = "京ICP备14007000号-8" # 网站备案号（展示于页脚）
start_year = 2002 # 创站年份（页脚自动生成 © 2002 - 2026）
# ==============================================================================
# 2. 激活主题配置 [theme]
# ==============================================================================
[theme]
name = "light" # 激活的主题名称，对应 themes/ 下的目录名（如 "default" 或 "light"）
# ==============================================================================
# 3. 作者档案与展示信息 [author]
# ==============================================================================
[author]
name = "金石碼农" # 作者姓名
maxim = "势利纷华，不近者为洁；智械机巧，不知者为高。" # 座右铭/名言
bio = "大学计算机讲师，腾讯云最具价值专家（TVP），多本计算机畅销书作者。" # 个人简述
avatar = "/static/images/avatar.png" # 作者头像路径
location = "北京, 中国" # 所在地
website = "https://yishulun.com" # 个人主页
email = "[email protected]" # 联系邮箱
donate_qrcode = "/assets/donate_qrcode.png" # 赞赏打赏二维码图片路径
# ==============================================================================
# 4. 社交平台直达链接 [social]
# ==============================================================================
[social]
github = "https://github.com/rixingyike" # GitHub 主页链接
twitter = "https://x.com/jinshimanong" # Twitter / X 主页链接
youtube = "https://youtube.com/@yishulun" # YouTube 频道
email = "[email protected]" # 邮箱直连 mailto:
zhihu = "https://zhihu.com/people/liyi2005" # 知乎主页
wechat = "/static/images/qrcode.png" # 微信二维码弹窗图
weibo = "https://weibo.com/ixiaochengxu" # 微博主页
bilibili = "https://space.bilibili.com/262757998" # 哔哩哔哩空间
rss = "/rss.xml" # RSS 订阅源路径
# ==============================================================================
# 5. 首页与版块展示设置 [homepage]
# ==============================================================================
[homepage]
posts_per_page = 8 # 首页文章列表每页显示数量
hero_title = "欢迎来到艺述论" # 首页 Hero 大图主标题
hero_subtitle = "一花一世界，一树一菩提。" # 首页 Hero 大图副标
hero_background = "/static/images/hero-bg.jpg" # 首页顶部 Hero 背景图
show_hero = true # 是否在首页开启 Hero 大图区域
# ==============================================================================
# 6. 分类与标签分页设置
# ==============================================================================
[categories]
posts_per_page = 8 # 单个分类列表每页文章数
[tags]
posts_per_page = 8 # 单个标签列表每页文章数
# ==============================================================================
# 7. 全局功能开关 [features]
# ==============================================================================
[features]
search = true # 开启本地 Lunr.js 离线全文检索
comments = true # 开启文章评论点赞互动模块
analytics = true # 开启网站访问数据统计
rss = true # 自动生成全站 rss.xml 订阅源
sitemap = true # 自动生成搜索引擎 sitemap.xml
# ==============================================================================
# 8. 顶部主导航菜单 [[menu.main]] (按 weight 升序排序)
# ==============================================================================
[[menu.main]]
name = "首页"
url = "/"
weight = 1
[[menu.main]]
name = "归档"
url = "/a/"
weight = 2
[[menu.main]]
name = "分类"
url = "/cat/"
weight = 3
[[menu.main]]
name = "标签"
url = "/tag/"
weight = 4
[[menu.main]]
name = "专栏"
url = "/c/"
weight = 5
[[menu.main]]
name = "友链"
url = "/f/"
weight = 6
[[menu.main]]
name = "项目"
url = "/p/"
weight = 7
[[menu.main]]
name = "关于"
url = "/about.html"
weight = 8
三、几个关键参数的避坑说明
1. domain 与 base_url 的区别
domain：必须填带协议头的线上正式域名（如https://yishulun.com，末尾不带斜杠）。系统在生成rss.xml、sitemap.xml和社交分享卡片时，需要用它拼出绝对 URL。base_url：当前编译环境的基础地址。本地写文章调试时填http://localhost:1111，确保本地图片和静态资源路径正常解析。
2. show_hero 在不同主题下的效果
- 在
default主题下：渲染一个大气的全屏图文横幅，带背景大图与「浏览文章/了解作者」两个 CTA 动作按钮； - 在
light主题下：渲染为现代极简的座右铭卡片，展示作者名言author.maxim； - 关闭 Hero：只要设为
show_hero = false，所有主题都会直接从文章列表开篇，干脆利落。
3. posts_per_page 与倒分页算法
posts_per_page 决定了每页容纳的文章数量。RustPress 的倒分页算法直接以该数值为基准划分历史归档编号，一旦定下来（比如每页 8 篇），老页面的 URL 和内容就永久固化，搜索引擎也喜欢这样。posts_per_page建议不要修改，或只在建站初修改一次，因为每次修改相当于重新生成全站，如果每次发文都修改一下，RustPress 的优势也就不复存在了。
4. 主题一键热切换
只要把 [theme] 下的 name = "default" 改为 name = "light"，保存文件，本地浏览器即刻无刷新切入全新主题。
下一篇，我们来看如何配置 Google Analytics 统计，给博客装上流量观察哨。
