跳转到主要内容

选项配置

了解如何通过选项指令自定义 Beancount 的行为，确保你的会计系统满足特定需求。本指南涵盖有效账本管理所需的核心配置选项。

Beancount 的行为通过放置在主账本文件开头的 option 指令来自定义。这些键值对控制着你的根账户名称、交易可承受的不平衡程度以及运行的扩展。⚙️

本页的每个选项均针对 Beancount 3.2.3 版本进行了验证，并且每个引用的错误信息都是该版本实际输出的。如果 Beancount 遇到无法识别的选项——例如 option "default_tolerance" "USD:0.01" 会报错 Invalid option: 'default_tolerance'——那么从旧指南中复制的选项就不会悄无声息地失败。在修改任何内容后，对你的文件运行 bea check 以进行验证。

核心配置选项​

这些选项控制着你账本的基本设置。

基本设置​

以下是你最常设置的一些选项。

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"
  • title：设置报告和 Web 界面的标题。默认为 Beancount。
  • render_commas：如果为 true，报告中的数字将使用千位分隔符格式化（例如 1,000,000.00）。默认为 false。1、TRUE、true 或 yes 均视为 true；其他任何字符串均视为 false。
  • plugin_processing_mode：值为 default（默认）或 raw。任何其他值都会以 Error for option 'plugin_processing_mode' 报错。

raw 并非 default 的温和版本——它是关闭 Beancount 自身处理阶段的开关。在 default 模式下，Beancount 会在你的插件之前运行 beancount.ops.documents，并在插件之后运行 beancount.ops.pad 和 beancount.ops.balance。在 raw 模式下，它只运行你自己列出的插件，因此 pad 指令永远不会被执行，balance 断言也永远不会被检查：

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

将该行改为 default，同样的文件会报错 Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little)。只有在你要故意重新实现这些阶段时，才使用 raw 模式。

账户名称自定义​

你可以重命名 Beancount 的五种基本账户类型。这并非装饰性的改动。 该选项重新定义了解析器接受哪些根名称，因此你文件中的每个账户都必须使用新名称，旧名称将变为无效。

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

在旧根名称上留下单个分录，文件将无法加载，并报错 Invalid account name: Assets:Banque:Courant。五个选项分别是 name_assets、name_liabilities、name_equity、name_income 和 name_expenses；每个值都必须是一个首字母大写的单词，且不能包含冒号，否则你会得到 Error for option 'name_assets': Invalid root account name 错误。应在开始账本时就重命名根账户，而非中途进行。

权益账户配置​

当 Beancount 总结一个期间时，它会合成多个权益账户——例如期初余额、留存收益和货币换算。这些选项用于命名这些账户。

每个值都是一个叶子名称，Beancount 会将其拼接在 name_equity 之下。 如果你自己编写权益根账户，会产生类似 Equity:Equity:Opening-Balances 的路径，这并非你本意。

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"
选项默认叶子账户产生的账户
account_previous_balancesOpening-BalancesEquity:Opening-Balances
account_previous_earningsEarnings:PreviousEquity:Earnings:Previous
account_current_earningsEarnings:CurrentEquity:Earnings:Current
account_previous_conversionsConversions:PreviousEquity:Conversions:Previous
account_current_conversionsConversions:CurrentEquity:Conversions:Current

account_rounding 是这个组中的例外：它接受一个完整的账户名称，并且会原样存储，这就是为什么上面的 Equity:Rounding 是正确的，而不是一个重复的前缀。它默认也是未设置的，在 Beancount 3.2.3 中设置它对加载没有影响——关于实际如何处理剩余差额，请参阅精度与容差。

精度与容差设置​

这些选项控制 Beancount 在交易中接受多大的不平衡。

默认容差配置​

Beancount 会根据交易分录中的小数位数，为每笔交易推断一个容差。这三个选项用于调整该推断过程。

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"
  • inferred_tolerance_default：每货币的基础容差下限，用于当交易没有小数可推断时。语法为 <currency>:<number>，其中 * 代表所有货币。重复该选项可设置多个货币的容差。
  • tolerance_multiplier：作为可接受误差的最小有效数字的倍数，默认值为 0.5。这不是百分比增加：1.2 会使每个推断的容差变为默认值的 2.4 倍。
  • infer_tolerance_from_cost：如果为 true，按成本持有的分录也会在成本货币中扩大容差。默认关闭。

旧选项名称 inferred_tolerance_multiplier 仍然可以设置相同的值，但它会报告一个 Renamed to 'tolerance_multiplier'. 的加载错误，因此 bea check 会因使用它而失败。请重命名它。

记账方法​

此选项设置选择减记哪个批次（lot）的默认规则。你可以在单个账户的 open 指令上为其指定不同的规则。

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 恰好接受七个名称：STRICT（默认）、STRICT_WITH_SIZE、NONE、FIFO、LIFO、HIFO 和 AVERAGE。任何其他值都会在加载时以 Error for option 'booking_method' 报错——包括 SIMPLE 和 FULL，它们从来都不是合法的记账方法。AVERAGE 在此处被接受，但其背后没有实现；在其下进行减记会引发 AVERAGE method is not supported 错误。有关在同一个账本中处理所有七种方法的信息，请参阅库存管理。

货币管理​

正确的货币配置对于准确的报告至关重要。

本位币​

本位币是你希望报告以之统计总额的货币。重复该选项可以声明多种本位币；这些值会累积，而不是互相替换。

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

声明本位币会告诉报告工具为每种货币单独生成一列。conversion_currency 指定一个虚拟货币名称，Beancount 会以零汇率将换算计入该货币；它默认为 NOTHING，设置它的唯一原因是选择一个你的账本中肯定不会用作真实商品的占位符。

文档管理​

Beancount 可以将交易链接到外部文件，如收据或发票。documents 选项为其指定一个要扫描的文件夹。

option "documents" "/home/user/Documents/beancount"

该块中的路径仅为示例——运行前请替换为你自己的路径。相关规则很严格，如果你弄错了，每一条都会静默地不起作用，而不是报错：

  • 该文件夹必须存在。 缺失的文件夹会导致加载失败，错误信息为 Document root '/no/such/place' does not exist。
  • 子文件夹即账户名称。 属于 Assets:US:BofA:Checking 的账单应放在 <root>/Assets/US/BofA/Checking/。直接放在根目录下的文件会被忽略。
  • 账户必须已开设。 在账本中从未开设的账户下发现的文档会被静默跳过，不会有任何警告。
  • 文件名以日期开头，格式为 YYYY-MM-DD.description.ext（例如 2025-07-28.amazon-order.pdf）。文件夹中的其他任何文件都会被忽略。
  • 路径可以是绝对的，也可以是相对于主账本文件的，并且该选项可以重复以指定多个文件夹。

插件系统​

Beancount 的功能可以通过插件进行扩展。

插件配置​

插件使用独立的 plugin 指令加载，而不是 option。 option "plugin" "..." 会以 Option 'plugin' may not be set 报错。

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

该文件能够加载是因为 auto_accounts 为你开设了两个账户；删除 plugin 行，它会报告 Invalid reference to unknown account 'Expenses:Food:Coffee'。需要配置的插件会接收第二个字符串作为配置，如 plugin "module" "config"。插件按照你编写的顺序运行，在 Beancount 自身的 documents 阶段之后，在其 pad 和 balance 阶段之前——除非你将 plugin_processing_mode 设置为 raw，这会完全丢弃这些阶段。

技术限制与约束​

这些选项控制 Beancount 解析器的技术层面。

字符串处理​

你可以设置多行字符串允许的最大行数，这样未终止的引号就会在你输入的位置附近被报告，而不是在文件末尾。

option "long_string_maxlines" "64"

插值精度​

默认情况下，Beancount 对两个不同任务使用同一种容差：填充缺失金额，以及判断交易是否平衡。开启此选项后，对于第一个任务使用最精确的推断容差，对于第二个任务使用最宽松的容差，这可以防止插值金额发生漂移。

option "use_precise_interpolation" "TRUE"

没有针对单个分录设置显式容差的选项。Beancount 3.2.3 唯一支持的显式容差语法是 balance 指令上的波浪号——4.271 ~ 0.01 RGAGX——并且它完全不需要任何选项。在交易分录内部使用波浪号是语法错误。

已弃用和已移除的选项​

旧指南仍会推荐的三个选项在 Beancount 3.2.3 中不存在。本块中的每一行都会导致加载失败：

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"
  • experiment_explicit_tolerances —— 它启用的分录级 ~ 语法已被移除；请改用 balance 指令的波浪号。
  • use_legacy_fixed_tolerances —— 固定的 0.005/0.015 容差已被移除；容差现在按交易推断，可通过 tolerance_multiplier 和 inferred_tolerance_default 调整。
  • default_tolerance —— 对于平衡校验已被 inferred_tolerance_default 取代，对于渲染已被 display_precision 取代。

另外三个选项仍然有效，但会报告弃用错误，这足以导致 bea check 失败：

  • inferred_tolerance_multiplier —— 已重命名为 tolerance_multiplier。
  • allow_pipe_separator —— 接受收款人与摘要之间的旧式 | 分隔符。
  • allow_deprecated_none_for_tags_and_links —— 接受在标签和链接位置使用字面量 None。

Fava 选项是独立的​

本页的所有内容都由 Beancount 自身读取。Fava 自己的设置根本不是 option 指令——它们是带日期的 custom "fava-option" 指令，Beancount 会忽略它们。将 Fava 设置写成 option 会以 Invalid option 报错。请参阅 Fava 选项 获取该列表。

推荐配置 ✅​

对于大多数用户，以下配置提供了一个稳健且合理的起点。它是一个文件，并且可以正常加载。

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

注释以 ; 开头。// 注释在 Beancount 中是语法错误，并且会导致文件其余部分无法解析。

此设置为一个新的 Beancount 账本提供了坚实的基础，确保了清晰的报告、合理的精度控制以及逻辑清晰的权益账户结构。

选项配置

来源：https://beancount.io/zh/docs/Basics/options-configuration