使用带日期的 custom "fava-option" 指令配置原生 Fava。这些设置与 Beancount 核心选项是分开的。
本参考基于 Beancount 3.2.3、beanquery 0.2.0 和 Fava 1.30.16 执行。该矩阵描述了该版本的特性。Beancount.io 有独立的仪表盘和后端；其暴露的设置并不能证明标准 Fava 的每个功能在那里都可用。
语法
值都是带引号的字符串，包括整数和布尔值。以下完整示例在 Beancount 和 Fava 中都能解析：
; Minimal Fava configuration
option "operating_currency" "USD"
2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "default-page" "income_statement/"
2000-01-01 custom "fava-option" "indent" "2"
2000-01-01 custom "fava-option" "show-closed-accounts" "false"日期是必需的。Fava 按日期顺序处理加载的自定义指令；后面的标量设置会覆盖前面的。重复的 collapse-pattern、import-dirs 和 insert-entry 设置会累积。插入规则使用它们的日期来选择目标位置，所以这些日期是有意义的。
要在本地复现这些示例，先安装 uv，然后创建一个临时环境：
uv venv .venv-fava-docs
uv pip install --python .venv-fava-docs/bin/python 'beancount==3.2.3' 'beanquery==0.2.0' 'fava==1.30.16'
source .venv-fava-docs/bin/activate
bean-check main.beancount
fava main.beancount先根据配置块创建 main.beancount，或者使用现有的账本。上面的 shell 命令使用 POSIX 路径。bean-check 检查 Beancount 语法和记账规则；Fava 还会检查它自己的选项名称和值。也请查看 Fava 的错误报告。
下面的默认值是从已安装的 FavaOptions 数据类中读取的，并与 带版本号的选项解析器 核对过。“未设置” 表示 None；空集合表示没有配置条目。值类型列描述的是带引号字符串的内容。
| 标准选项 | 值类型 | 默认值 |
|---|---|---|
language | 支持的翻译代码 | 未设置 |
locale | Babel 语言区域代码 | 未设置；当核心 render_commas 为 true 时变为 en |
default-page | 相对报告路径，可选带过滤器 | income_statement/ |
fiscal-year-end | 财年结束日期 MM-DD | 12-31 |
indent | 整数 | 2 |
currency-column | 整数 | 61 |
show-closed-accounts | 布尔值 | false |
show-accounts-with-zero-transactions | 布尔值 | true |
show-accounts-with-zero-balance | 布尔值 | true |
show-metadata-indicators | 布尔值 | true |
collapse-pattern | 账户正则表达式；可重复 | 空列表 |
sidebar-show-queries | 整数 | 5 |
default-file | 文件路径，或省略值以指定此文件 | 未设置 |
insert-entry | 账户正则表达式；可重复，带日期的位置 | 空列表 |
auto-reload | 布尔值 | false |
use-external-editor | 布尔值 | false |
import-config | 导入配置路径 | 未设置 |
import-dirs | 目录路径；可重复 | 空列表 |
invert-gains-losses-colors | 布尔值 | false |
invert-income-liabilities-equity | 布尔值 | false |
conversion-currencies | 单个字符串中的空格分隔货币代码 | 空元组 |
account-journal-include-children | 布尔值 | true |
uptodate-indicator-grey-lookback-days | 整数 | 60 |
upcoming-events | 整数 | 7 |
布尔值请用 "true" 或 "false"。比较不区分大小写："TRUE" 也会启用选项。任何不是 "true" 大小写变体的字符串都被视为 false。其整数解析器检查的是整数语法，而不是正数范围；请使用正的布局尺寸和非负的计数。
显示与本地化
language
设置界面翻译语言，例如 "en"、"de" 或 "zh_CN"。当未设置时，Fava 会与浏览器协商。语言区域必须附带 Fava 提供的翻译；仅凭语法上有效的语言代码是不够的。
locale
设置数字格式，与界面语言无关，例如 "en_US" 或 "de_DE"。没有这个选项时，Fava 会使用其非本地化的数字格式。核心选项 option "render_commas" "TRUE" 提供 en 后备。它不会继承浏览器语言。
导航与布局
default-page
设置账本内的目标页面，例如 "balance_sheet/" 或 "journal/?time=year"。从可用的标准 Fava URL 中复制账本代字 (slug) 后面的部分。不要加前斜杠 /：报告路径是相对于该账本的。
fiscal-year-end
设置财年时间过滤器的边界。例如，"03-31" 将财年结束于 3 月 31 日。它支持财年和季度过滤器，但不会改变交易日期。Fava 还接受大于 12 的月份值，用来标记在下一年日历年度结束的财年标签。
indent
设置生成的条目和编辑器格式的过账缩进。使用正整数，例如 "4"。
currency-column
设置保存或对齐过账时的货币对齐列。它同时也确定了编辑器的垂直参考线。默认值为 "61"。
内容可见性
show-closed-accounts
在报告账户树中包含已关闭的账户。无论此设置如何，余额非零的账户始终可见。
show-accounts-with-zero-transactions
如果关闭，账本中无交易记录的账户将不出现在报告账户树中。它不会隐藏余额非零的账户。
show-accounts-with-zero-balance
控制是否在账户树中显示余额为零的账户。通过 "false" 关闭它，可以让树更短。
show-metadata-indicators
控制是否在日志视图中显示小的元数据徽章。设为 "false" 可以隐藏徽章，但不会从账本中移除元数据。
collapse-pattern
匹配要在账户树中折叠的账户名称。需要多个模式时，可重复该指令。例如，"^Assets:Investments" 会折叠该账户及其子账户。
sidebar-show-queries
限制在侧边栏中链接的已保存查询数量。设为 "0" 会隐藏那些链接。参见 自定义链接和查询。
文件管理
default-file
选择编辑器最初打开的文件，以及新条目的后备目录。相对路径是从包含该指令的文件所在目录开始解析的。如果没有值，则选择包含该指令的文件。如果没有这个选项，则主账本文件作为后备。该文件还必须被包含在账本中，才能作为可编辑的源。
insert-entry
将新条目放在 匹配的自定义指令之前，并且在该指令所在的文件中插入。其正则表达式从开头匹配账户名称；它从不搜索原始文件行。Fava 从最后到最先前逐条考虑交易的分录。对于第一个可匹配的账户，它选择日期 严格早于 新条目的最新规则。如果没有匹配，它会追加到默认文件。插入操作以 实现 为准对于这些规则，你应参考该实现。
在同一个目录中创建这三个文件。main.beancount 提供账户并包含：
; main.beancount
option "title" "Insertion Demo"
option "operating_currency" "USD"
include "january.beancount"
include "february.beancount"
2000-01-01 open Assets:Checking USD
2000-01-01 open Assets:Cash USD
2000-01-01 open Assets:Wallet USD
2000-01-01 open Expenses:Food USD
2000-01-01 custom "fava-option" "default-file"
2024-01-01 custom "fava-option" "insert-entry" "^Expenses:Food$"january.beancount 文件如下：
; january.beancount
2024-01-01 custom "fava-option" "insert-entry" "^Assets:Checking$"february.beancount 文件如下：
; february.beancount
2024-02-01 custom "fava-option" "insert-entry" "^Assets:Checking$"用 main.beancount 启动 Fava，通过其交易表单添加这些交易；它们是插入操作的输入，不是预先包含的额外文件：
2024-01-15 * "January groceries"
Expenses:Food 10.00 USD
Assets:Checking -10.00 USD
2024-02-01 * "Same-day boundary"
Expenses:Food 20.00 USD
Assets:Checking -20.00 USD
2024-02-15 * "February groceries"
Expenses:Food 30.00 USD
Assets:Checking -30.00 USD
2024-02-16 * "Cash groceries"
Expenses:Food 40.00 USD
Assets:Cash -40.00 USD
2024-02-17 * "Unmatched cash transfer"
Assets:Cash 50.00 USD
Assets:Wallet -50.00 USD前两个条目放入一月规则之前。第三个放入二月规则之前。第四个尝试 Assets:Cash，找不到匹配，于是使用主文件中的 Expenses:Food 规则。第五个没有可匹配账户，则追加到 main.beancount。批量保存时，插入的条目会更新规则的行号。
auto-reload
当 Fava 检测到外部源发生变化时，自动重新加载页面。当设为 false 时，Fava 会提供一个重载通知。通过 Fava 自身进行的更改已经触发重载。
use-external-editor
通过 beancount:// URL scheme 打开源文件链接。在运行浏览器的电脑上安装一个处理器，并确保它能够访问账本文件。这不是一个自动连接到托管服务器上文件的机制。
import-config
指向一个 Python 导入器配置文件。这是一个集成设置：在使用“导入”报告之前，需要创建该配置并安装其导入器依赖项。上面三个受限的包不提供银行导入器配置。
import-dirs
添加一个用于扫描导入候选的目录。重复该指令可添加多个目录。请使用真实可访问的目录；设置选项并不会创建它们。
财务显示
unrealized
**不是标准 Fava 1.30.16 的选项。**如果你添加它，Fava 会报告 Unknown option 后跟名称用反引号括起来。不要用它配置标准的未实现收益科目。
Beancount.io 的源码快照在 2026-09-07 审查时，确实在其后端选项解析器和仪表盘“设置”表中暴露了一个独立的字符串字段 unrealized,默认值为 "Unrealized"。这可以验证该字段存在。但它并不能说明修改它会创建 Income:Unrealized 或 Expenses:Unrealized，也不能说明某个特定部署运行的是这个快照。
invert-income-liabilities-equity
在损益表和资产负债表中，交换显示时的收入、负债和权益的符号。费用保持其符号。日记账、账户日记和已存储的记录不会改变。
conversion-currencies
用单个字符串中的空格分隔列表替换转换下拉框的选择，例如：
; Conversion dropdown
2000-01-01 custom "fava-option" "conversion-currencies" "USD EUR"重复此选项会替换之前的列表。当未设置时，Fava 会提供运营货币以及它能识别的 ISO 4217 货币。
account-journal-include-children
默认情况下，在账户日记中包括子账户的条目。设为 "false" 则仅显示该账户。
invert-gains-losses-colors
在按市值计价（market-value）的资产负债和试算平衡 表中，颠倒未实现盈利和亏损所用的颜色。它只改变颜色，不改变金额或账户名。
监控
uptodate-indicator-grey-lookback-days
控制灰色新鲜度指示器的回看期。在账户的 open 指令下添加 fava-uptodate-indication: TRUE，以启用账户状态指示器。参考 UI 元数据示例。
upcoming-events
控制在指定天数内即将发生的事件在侧边栏的通知计数。"0" 会禁用计数。
推荐配置
以下是针对上述标准环境的完整配置起点。它仅调整显示设置，不会加载插件或要求额外文件：
option "operating_currency" "USD"
2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "locale" "en_US"
2000-01-01 custom "fava-option" "default-page" "income_statement/"
2000-01-01 custom "fava-option" "fiscal-year-end" "12-31"
2000-01-01 custom "fava-option" "indent" "2"
2000-01-01 custom "fava-option" "currency-column" "61"
2000-01-01 custom "fava-option" "show-closed-accounts" "false"
2000-01-01 custom "fava-option" "show-accounts-with-zero-transactions" "true"
2000-01-01 custom "fava-option" "show-accounts-with-zero-balance" "false"
2000-01-01 custom "fava-option" "show-metadata-indicators" "true"
2000-01-01 custom "fava-option" "collapse-pattern" "^Assets:Investments"
2000-01-01 custom "fava-option" "sidebar-show-queries" "5"
2000-01-01 custom "fava-option" "auto-reload" "false"
2000-01-01 custom "fava-option" "use-external-editor" "false"
2000-01-01 custom "fava-option" "invert-income-liabilities-equity" "false"
2000-01-01 custom "fava-option" "invert-gains-losses-colors" "false"
2000-01-01 custom "fava-option" "conversion-currencies" "USD EUR"
2000-01-01 custom "fava-option" "account-journal-include-children" "true"
2000-01-01 custom "fava-option" "upcoming-events" "7"
2000-01-01 custom "fava-option" "uptodate-indicator-grey-lookback-days" "60"查看你的当前选项
在标准 Fava 中，打开其帮助 → 选项页面，查看当前版本的参考信息；更改指令后查看Errors报告。官方 1.30.16 选项帮助 解释了这些设置。
在 Beancount.io 仪表盘 中，打开某个账本的“设置”页面。其 Fava Options 表格显示的是后端返回的子集。此界面在产品源码快照中验证过，未通过经过身份验证的生产会话。显示一个字段不表示托管仪表盘实现了标准 Fava 的编辑器、导入或 URL 路由。