2.安装与工具链配置

在正式开启我们的复式记账旅程之前，我们需要先搭建好本地的工具链。就像任何现代的 Python 项目一样，一个干净、隔离的环境是保证项目稳定性和可维护性的第一步。我们不建议将 Beancount 直接安装到操作系统的全局 Python 环境中，因为这可能会与系统自身的工具或其他 Python 项目产生依赖冲突。

首先，我们需要确保你的系统中已经安装了 Python。Beancount v3 版本要求 Python 3.8 或更高版本。你可以通过在终端（或者在 Windows 上是命令提示符或 PowerShell）中运行以下命令来检查你的 Python 版本：

python3 --version
# 或者在某些系统上是
python --version

如果系统提示找不到命令，或者版本低于 3.8，你需要先安装或升级 Python。请访问官方网站 python.org 下载适合你操作系统的最新稳定版本。在安装时，请务必勾选 "Add Python to PATH" 选项，这会让你在命令行中更方便地使用 Python。

安装好 Python 之后，我们推荐使用 pipx 来管理 Beancount 的安装。pipx 是一个专门用于安装和运行 Python 命令行工具的实用程序，它会为每个工具创建一个独立的虚拟环境，从而完美地解决了依赖隔离的问题。这比手动创建和激活虚拟环境要简单得多，也更不容易出错。

如果你的系统中还没有 pipx，可以通过以下命令安装它：

python3 -m pip install --user pipx
python3 -m pipx ensurepath

执行完这两条命令后，你可能需要重新启动你的终端，以使 pipx 的路径生效。

Beancount pipx 安装

有了 pipx 这个强大的工具，安装 Beancount 就变得异常简单了。在你的终端中，只需运行一条命令：

pipx install beancount

pipx 会自动完成以下工作：

1. 创建一个专用的虚拟环境，避免污染你的系统 Python。
2. 从 PyPI（Python Package Index）下载 Beancount 及其所有依赖项。
3. 将 Beancount 的核心可执行文件（如 bean-check）安装到你的系统路径中，让你可以在任何地方调用。

安装完成后，你可以通过运行 pipx list 来确认 Beancount 是否已成功安装。它会列出所有通过 pipx 安装的工具，你应该能看到 beancount 在列表中。

现在，让我们验证一下安装。运行 bean-check 命令，如果它没有报错，而是输出了使用说明，那么恭喜你，Beancount 的核心部分已经准备就绪了。

bean-check

你可能会看到类似下面的输出，这表明一切正常：

usage: bean-check [-h] [-v] filename
bean-check: error: the following arguments are required: filename

这个提示告诉你 bean-check 需要一个文件名作为参数，这正是我们所期望的。它说明工具已经正确安装，并且正在等待你的指令。

Beancount pip 安装

虽然我们强烈推荐使用 pipx，但了解传统的 pip 安装方式也是有益的，特别是当你已经熟悉 Python 虚拟环境的工作流时。

首先，你需要手动创建并激活一个虚拟环境：

# 创建一个名为 beancount-venv 的虚拟环境
python3 -m venv beancount-venv

# 激活虚拟环境
# 在 Linux 或 macOS 上
source beancount-venv/bin/activate
# 在 Windows 上 (PowerShell)
.\beancount-venv\Scripts\Activate.ps1
# 在 Windows 上 (CMD)
.\beancount-venv\Scripts\activate.bat

激活后，你的终端提示符通常会显示环境名称（例如 (beancount-venv) $），这表示你现在处于这个隔离的环境中。接下来，使用 pip 安装 Beancount：

pip install beancount

这种方式与 pipx 的最终效果类似，但需要你手动管理环境的激活和退出。当你不再需要使用 Beancount 时，只需在终端中输入 deactivate 即可退出虚拟环境。

Beancount 源码编译

对于希望使用最新开发版本，或者有意向为 Beancount 项目贡献代码的开发者来说，从源码编译安装是最佳选择。这让你能够获取到尚未发布到 PyPI 的最新功能和修复。

首先，你需要从 GitHub 克隆 Beancount 的官方仓库：

git clone https://github.com/beancount/beancount.git
cd beancount

Beancount 的构建过程依赖于一些工具，特别是 meson 和 ninja。如果你还没有安装它们，可以通过 pip 来安装：

pip install meson ninja

接下来，我们使用 pip 以“可编辑模式”（editable mode）来安装 Beancount。这种模式会创建一个指向源码目录的链接，而不是复制文件。这样，你对源码的任何修改都会立即生效，无需重新安装。

# --no-build-isolation 确保使用当前环境的依赖
# --editable 表示可编辑模式安装
pip install --no-build-isolation --editable .

这个过程会编译 Beancount 中需要编译的部分（例如解析器），并将工具安装到你的环境中。安装完成后，你可以随时通过 git pull 来更新源码，并重新运行上面的安装命令来应用更新。

Windows Beancount 安装

在 Windows 上安装 Beancount，特别是从源码编译，可能会遇到一些挑战，主要是因为编译 C/C++ 扩展需要特定的构建工具。不过，对于大多数用户来说，最简单的方法是直接安装 beanquery 包，它包含了 Beancount v3 的核心功能，并且通常有预编译的二进制轮子（wheel），可以避免复杂的编译过程。

打开你的 PowerShell 或命令提示符，运行：

pip install beanquery

beanquery 是 Beancount v3 生态中的一个核心组件，它提供了强大的查询功能。安装它会自动拉取并安装 beancount 作为依赖。

如果你确实需要从源码编译（例如，为了开发或使用最新的未发布代码），你需要准备一个完整的 C++ 开发环境：

1. 安装 Visual Studio Build Tools：你需要安装 "使用 C++ 的桌面开发" 工作负载。这会提供 MSVC 编译器。
2. 安装 Flex 和 Bison：这是解析器生成器。你可以从 winflexbison 下载，并将其解压后的目录添加到系统的 PATH 环境变量中。
3. 安装 Python 开发头文件：确保你的 Python 安装包含了开发头文件（通常在安装 Python 时选择 "Install development libraries" 或类似选项）。

准备好环境后，就可以按照 "源码编译" 一节中的步骤进行操作了。建议在 "x64 Native Tools Command Prompt for VS 20XX" 中执行构建命令，以确保所有环境变量都已正确设置。

Emacs Beancount 集成

Emacs 用户有福了，Beancount 拥有非常出色的 Emacs 集成支持。官方提供了一个独立的 beancount-mode，提供了语法高亮、自动缩进、指令补全等强大功能。

首先，你需要从 GitHub 获取 beancount-mode 的代码：

git clone https://github.com/beancount/beancount-mode.git

接下来，将以下代码添加到你的 Emacs 配置文件（~/.emacs 或 ~/.emacs.d/init.el）中，以告诉 Emacs 在哪里可以找到这个模式：

;; 将 beancount-mode 目录添加到 load-path
(add-to-list 'load-path "/path/to/your/beancount-mode")

;; 自动为 .beancount 和 .bean 文件启用 beancount-mode
(require 'beancount)
(add-to-list 'auto-mode-alist '("\\.beancount\\'" . beancount-mode))
(add-to-list 'auto-mode-alist '("\\.bean\\'" . beancount-mode))

将 /path/to/your/beancount-mode 替换为你实际克隆仓库的路径。重启 Emacs 后，当你打开一个 .beancount 文件时，beancount-mode 就会自动激活。你还可以通过 M-x beancount-reload 来重新加载账本，以便在编辑后立即进行验证。

Vim Beancount 语法

Vim 用户同样可以享受语法高亮和文件类型检测的便利。社区贡献的 vim-beancount 插件可以轻松实现这一点。

如果你使用 vim-plug 作为插件管理器，只需在你的 ~/.vimrc 或 ~/.config/nvim/init.vim 中加入：

Plug 'nathangrigg/vim-beancount'

然后运行 :PlugInstall 即可。

如果你不使用插件管理器，也可以手动下载 vim-beancount 的 syntax/beancount.vim 和 ftdetect/beancount.vim 文件，并将它们放置到你的 ~/.vim/ 目录中。

VSCode Beancount 扩展

对于 Visual Studio Code 用户，安装 Beancount 支持非常简单，就像安装任何其他 VSCode 扩展一样。

1. 打开 VSCode。
2. 点击左侧活动栏中的扩展图标（或按 Ctrl+Shift+X）。
3. 在搜索框中输入 "Beancount"。
4. 你会看到几个选项，其中比较流行的一个是由 Lencerf 开发的 "Beancount" 扩展。点击 "Install"。

这个扩展提供了语法高亮、自动补全（账户、货币等），并且集成了 bean-check，可以在你编辑时实时检查语法错误，并在 "问题" 面板中显示出来，极大地提高了工作效率。

Beancount 安装验证

至此，我们已经介绍了多种安装方式和主流编辑器的配置。现在，让我们进行一次全面的安装验证，确保整个工具链都已准备就绪。

第一步：创建一个测试账本 使用你喜欢的编辑器，创建一个名为 test.beancount 的文件，并填入以下最简内容：

option "title" "Test Ledger"
option "operating_currency" "USD"

2024-01-01 open Assets:Bank
2024-01-01 open Equity:Opening-Balances

2024-01-01 * "Opening Balance"
  Assets:Bank              1000.00 USD
  Equity:Opening-Balances

第二步：使用 bean-check 验证 在终端中，导航到 test.beancount 所在的目录，然后运行：

bean-check test.beancount

如果一切正常，这个命令将不会有任何输出，并直接返回到命令提示符。这是 bean-check 在告诉你：“账本格式正确，没有发现错误”。如果存在任何问题（比如拼写错误、不平衡的交易），它会清晰地报告错误所在的行号和原因。

第三步：使用 bean-query 查询 接下来，我们验证查询功能是否正常。运行 bean-query 并加载你的测试账本：

bean-query test.beancount

你会看到一个交互式的提示符 beanquery>。在这里，我们可以输入 BQL（Beancount Query Language）命令来查询数据。输入以下命令并按回车：

SELECT account, SUM(position) WHERE account ~ 'Assets' GROUP BY account;

如果安装正确，你应该会看到类似下面的输出，显示了 Assets:Bank 账户的余额：

  account      | SUM(position)
---------------+---------------
  Assets:Bank  | 1000.00 USD
(1 row)

输入 exit 或按 Ctrl+D 退出 bean-query。

第四步：验证编辑器集成 最后，打开你的编辑器（Emacs, Vim, 或 VSCode），加载 test.beancount 文件。检查以下几点：

• 关键字（如 option, open, transaction）是否高亮显示？
• 账户名（如 Assets:Bank）和货币（如 USD）是否有特殊的颜色或样式？
• 如果你在 bean-check 中故意制造一个错误（例如，拼错 open 为 opne），编辑器或其集成的 Linter 是否能立即标记出这个错误？

如果以上所有步骤都成功了，那么恭喜你！你的 Beancount 工具链已经完全配置好了。你已经准备好进入下一章，学习复式记账的核心原理，并开始构建你自己的个人财务账本了。