从克隆到跑通：15 分钟跑通 AppFlowy，开源 Notion 替代方案实操指南-编程实验室

从克隆到跑通：15 分钟跑通 AppFlowy，开源 Notion 替代方案实操指南

【免费下载链接】AppFlowyBring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.项目地址: https://gitcode.com/GitHub_Trending/ap/AppFlowy

项目文档在 Notion、会议纪要在飞书、需求表格又躺在本地 Excel，想把它们收拢到一个能自托管、AI 能力可以自己接的协同工作区里，AppFlowy 就是干这件事的：开源的 Notion 替代方案，文档、数据库、看板与 AI 助手都内置在同一个 Flutter + Rust 客户端中，数据默认只落在你机器上的本地 SQLite 里。

选型对比：三条路，10 秒选一条

路径	适用人群	预估耗时	前置依赖
源码编译	想改代码、追新功能的开发者	20~40 分钟	Flutter ≥3.27.4、Rust 1.85
官方一键脚本 install.sh	Linux 服务器 / 快速体验	3~5 分钟	仅需 curl 或 wget
包管理器	日常只使用、不关心代码的桌面用户	2~3 分钟	已装 Flatpak 或 Snap

只想每天打开写东西，走后两行；打算读源码、提 PR，直接看下一节。

装好依赖并验证

系统：Ubuntu 18.04+ / macOS 10.15+ / Windows 10+，内存 8GB 起步
Flutter SDK：≥3.27.4（frontend/appflowy_flutter/pubspec.yaml 中environment字段的硬性下限）
Rust：1.85，由 frontend/rust-toolchain.toml 锁定，装好 rustup 后cargo make会自动拉取
磁盘预留 5GB；网络需能访问 pub.dev 与 crates.io

跑一句命令确认两条工具链都就位：

flutter --version # 输出 flutter 3.27.4 或更高 rustc --version # 期望 rustc 1.85.x

跑起来：AppFlowy 源码编译安装步骤

# 把代码拉到本地 git clone https://gitcode.com/GitHub_Trending/ap/AppFlowy cd AppFlowy/frontend

# 先让 cargo-make 核对 Flutter 与 protobuf 环境 cargo make env_check

# 编译 Rust 核心库 dart-ffi，随后自动拉起 Flutter 桌面端 cargo make appflowy-core-dev

最后一条命令对应 frontend/scripts/makefile/desktop.toml 里的appflowy-core-dev任务：先给dart-ffi这个 Rust 包做 debug 编译，成功后自动flutter run打开窗口。首次编译 10~20 分钟属正常，跑完你会看到：

Finished `dev` profile [unoptimized + debuginfo] target(s) Launching lib/main.dart on macOS in debug mode...

窗口标题是 AppFlowy、左侧出现默认工作区，就算通了。如果卡在这一步，先回到上一节核对工具链版本。

不想编译？两条快捷路径

官方脚本直接拉最新预编译包（仅 Linux）：sh install.sh
包管理器：flatpak install io.appflowy.AppFlowy或snap install appflowy

首跑过一遍自检清单

默认工作区加载出 Getting started、To-dos 等模板节点 —— 空白页就重启一次
控制台日志没有ERROR级输出 —— 重点看appflowy_server与ffi两个 tag
数据目录里已生成AppFlowy-xxxx.afdb与AppFlowy-xxxx/文件目录 —— Linux 在~/.local/share/io.appflowy/AppFlowy/，macOS 在~/Library/Application Support/io.appflowy/AppFlowy/
侧边栏 AI Chat 能打开对话页 —— 未填密钥时它只会停在配置引导，不算故障

两个高频场景实操

创建第一个 Space 并切换权限

侧边栏顶部选「+ New」→「Space」，弹窗里填 Space 名称，Permission 一行控制可见范围：选 Public 则全工作区成员可进，改选 Private 就只有你和管理员可见。点 Create 后，这个 Space 立刻挂在侧边栏，里面可混放文档、表格、看板和日历。

创建 Space 时选择 Public 或 Private 权限。

打开 Ask AI 并接入 OpenAI 兼容模型

点侧边栏的 Ask AI 进入对话页，在模型设置里填 Base URL、API 密钥、模型名三个字段。密钥加密写入本地 SQLite，不发往 AppFlowy 任何远端；填完直接发一句话测试，模型正常返回即链路打通。模型不必用 OpenAI 官方，任意 OpenAI 兼容接口都可以；想彻底离线就选 llama.cpp 本地推理。

侧边栏加号菜单里的视图与 AI 入口。

三个高频报错排查

cargo 直接报the lock file requires cargo 1.x→ 当前工具链比项目要求的新，锁文件不兼容 → 执行rustup default 1.85切回锁定版本再重跑。
flutter run启动后闪退→ Linux 缺少 GTK 等系统库 → 按flutter doctor列出的缺失项装上对应libgtk-3-dev，再复跑一次。
AI 对话返回 401 或空响应→ Base URL 少了/v1路径段或密钥填错 → 回到 Ask AI 设置页核对后重试。