企业官网建设流程全解析

Actual 实验性功能（Experimental Features）完全指南：从开启开关到源码级工作原理

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual

新功能的开发与测试往往需要漫长周期，为了让用户提前尝鲜并收集真实反馈，Actual 内置了一套**实验性功能（Experimental Features）**机制。本文以官方文档 packages/docs/docs/experimental/index.md 为主体，结合桌面端设置界面与核心包的类型定义、钩子实现等源码，系统讲解实验性功能的概念、开启方式、风险提示、当前可用的功能清单，以及它在代码层面“如何被存储、如何被读取、如何生效”的完整链路。读完本文，你将能够在自己的 Actual 实例上安全地启用目标功能，并理解为什么这些开关是"跟随预算同步"而非本地独享的。

什么是实验性功能

Actual 官方文档给出的定义非常清晰：新功能从开始开发到完全成熟、经过充分测试，往往需要很长时间。为了让开发迭代更顺畅，同时让用户尽早参与反馈，Actual 引入了experimental features这套机制。

它的核心设计原则有两条：

1. 默认关闭、自愿开启（opt-in）：实验性功能一般都需要用户主动启用，如果用户不开启，用户体验不会有任何变化，不会因为代码中存在实验性开关而影响日常使用。
2. 仍在积极开发中：这些功能尚未经过完整测试，处于活跃开发状态，因此官方文档强烈建议：一旦启用任何实验性功能，务必定期备份数据。

从源码结构来看，"实验性功能"并不是一套独立子系统，而是借助 Actual 已有的**同步偏好（synced prefs）**体系实现的"功能开关（feature flag）"机制。核心类型的定义位于 packages/loot-core/src/types/prefs.ts，其中FeatureFlag类型枚举了当前仓库中所有受控的实验性功能名称。

如何查看与开启实验性功能

根据官方文档的操作路径，启用实验性功能只需以下几步：

1. 打开 Actual 应用，进入Settings（设置）；
2. 在设置中找到Show advanced settings（显示高级设置）并展开；
3. 进入Experimental features（实验性功能）板块。

进入后你会首先看到一个警告提示框，这是官方对风险的正式声明（文案与设置组件中的实现完全一致，见 Experimental.tsx）：

Experimental features.These features are not fully tested and may not work as expected. THEY MAY CAUSE IRRECOVERABLE DATA LOSS. They may do nothing at all. Only enable them if you know what you are doing.

（实验性功能。这些功能未经完整测试，可能无法按预期工作。它们可能导致不可恢复的数据丢失，也可能完全没有任何效果。只有在你清楚自己在做什么时才启用它们。）

你必须先点击"I understand the risks, show experimental features"（我了解风险，显示实验性功能）按钮，同意免责声明后，才能看到当前可用的实验性功能列表。

文档特别说明：上图列出的功能（Goal templates、Rule action templating、Context menus、Pluggy.ai Bank Sync 等）只是示例，实际可用的实验性功能会随版本发布而不断变化——不同版本的 Actual 会展示不同的功能集合。

源码视角：开关如何被读取与存储

实验性功能的开关并不是"一次性点击"那么简单，它在代码层面有完整的存储与读取链路。

开关类型的统一管理

在 packages/loot-core/src/types/prefs.ts 中，FeatureFlag联合类型枚举了所有受控开关名，例如newSidebarUI、goalTemplatesEnabled、formulaMode、currency、sankeyReport、monteCarloReport等。任何 UI 组件要读取实验性开关，都必须以这些名字为准，从类型层面杜绝了"开关名写错"这类低级错误。

开关如何存储：跟随预算同步的偏好

同文件 prefs.ts 中，SyncedPrefs类型明确把`flags.${FeatureFlag}`列为跨设备同步偏好（Cross-device preferences）。也就是说：

• 实验性开关以flags.功能名这样的键存储；
• 该偏好会随预算数据一起在不同设备间同步——你在桌面端开启的功能，在移动端等同步设备上同样生效；
• 这一点与"仅本地生效"的LocalPrefs（存储在 localStorage）有本质区别，见 prefs.ts。

开关如何被 UI 读取

桌面端设置界面通过 useFeatureFlag 钩子读取开关状态。其实现逻辑值得细读：

1. 通过useSyncedPref读取flags.${name}对应的同步偏好值；
2. 若偏好值为undefined（从未设置过），则回落到DEFAULT_FEATURE_FLAG_STATE中定义的默认值；
3. 否则将字符串值与'true'比较，得到最终的布尔状态。

关键设计是默认值表DEFAULT_FEATURE_FLAG_STATE（useFeatureFlag.ts）：当前仓库中所有实验性功能的默认状态均为false，这从源码层面保证了"不开启则体验不变"的 opt-in 原则——即使某个版本的代码已经包含实验性逻辑，只要用户不主动把flags.xxx设为'true'，该功能就不会激活。

设置界面的实现细节

实验性功能的设置界面组件位于 packages/desktop-client/src/components/settings/Experimental.tsx，其中有两个值得注意的实现模式：

FeatureToggle：通用功能开关组件

FeatureToggle组件接收flag（功能名）、feedbackLink（反馈链接）、note（附加说明）等参数，内部通过useFeatureFlag读取状态，通过useSyncedPref写入开关（Experimental.tsx）：

• 复选框的onChange会将当前值取反后写入flags.${flagName}；
• 若配置了feedbackLink，开关旁会显示 "(give feedback)" 链接，方便用户直接向开发者反馈；
• 若配置了note，会在开关下方以警示色显示补充说明——例如已废弃的功能会标注 "Deprecated" 提示。

条件渲染与权限控制

ExperimentalFeatures主组件（Experimental.tsx）负责：

• 初始状态只展示风险声明与确认链接，点击后才展开功能列表（expanded状态控制）；
• 部分功能存在父子依赖关系，例如只有先启用goalTemplatesEnabled后，才会显示子功能goalTemplatesUIEnabled（Budget automations UI）；
• 服务端类功能使用独立的ServerFeatureToggle组件，会根据同步服务器在线状态、用户权限（Permissions.ADMINISTRATOR）与多用户模式动态决定是否显示，并且某些条目被设计为不可切换（disableToggle），比如仍处于计划阶段的 "Client-Side plugins"。

当前仓库中的实验性功能一览

结合设置界面实现与FeatureFlag类型定义，当前仓库中实际受控的实验性功能包括（以下均可在 Experimental.tsx 中逐一找到对应开关）：

这些功能中，报表类（Sankey、Balance Forecast、Budget Analysis、Monte Carlo）、公式类（formulaMode、goalTemplates）与银行同步类（enableBanking、akahuBankSync）在仓库文档中均有对应的独立专题文档，例如 experimental/sankey-report.md、experimental/monte-carlo-analysis.md、experimental/formulas.md、experimental/goal-templates.md 等，需要深入了解某个功能的具体用法时，可对照阅读。

启用实验性功能的风险与建议

结合官方文档与源码中的警告文案，启用实验性功能时有几点需要明确：

1. 存在数据丢失风险：设置界面明确声明 "THEY MAY CAUSE IRRECOVERABLE DATA LOSS"，这些功能未经完整测试，可能出现数据损坏、功能失效甚至完全无效的情况。
2. 务必定期备份：官方建议在启用任何实验性功能后保持规律的备份习惯，这样即使出现意外也能恢复到安全状态。
3. 开关是"预算级"而非"设备级"：由于开关存储为同步偏好flags.${name}，它会随预算数据同步到其他设备。在多设备使用场景下，开启前请确认自己了解这一行为。
4. 功能集合随版本变化：不同版本会新增、调整或废弃实验性功能（如actionTemplating已被标记为 Deprecated），查看当前版本可用列表应以设置页面实际展示为准。

小结

Actual 的实验性功能机制，本质上是"以同步偏好为存储介质、以 feature flag 为类型约束、以设置界面为交互入口"的一整套渐进式发布管道：新功能在开发早期即可通过 opt-in 开关提供给用户测试，收集反馈后再逐步走向稳定。对于普通用户，只需要记住官方文档的三步操作——Settings -> Show advanced settings -> Experimental features，同意免责声明后按需勾选；对于开发者或深度用户，则可以顺着 prefs.ts → useFeatureFlag.ts → Experimental.tsx 这条链路，完整理解开关从存储、读取到渲染的全过程。

无论你处于哪个角色，都请牢记那条贯穿始终的警告：开启实验性功能前，先做好数据备份。

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual