3分钟解决AFFiNE项目GitHub CodeSpaces开发环境构建难题：新手也能轻松上手的完整指南

AFFiNE 是一个开源、一体化的工作区和操作系统，适用于组装您的知识库等的所有构建块 - 维基、知识管理、演示和数字资产。它是 Notion 和 Miro 的更好替代品，通过 GitHub CodeSpaces 可以快速搭建开发环境，让您无需复杂配置即可开始贡献代码或体验最新功能。

🚀 为什么选择 GitHub CodeSpaces 开发 AFFiNE？

GitHub CodeSpaces 提供了一个云端开发环境，无需在本地安装依赖，只需浏览器即可访问完整的开发工具链。对于 AFFiNE 这样的复杂项目，这意味着您可以：

• 跳过繁琐的本地环境配置步骤
• 避免因系统差异导致的依赖冲突
• 随时随地在任何设备上继续开发
• 快速体验最新代码变更

🔍 准备工作：您需要什么？

开始前，请确保您拥有：

• GitHub 账号（需绑定信用卡，免费计划提供每月 60 小时使用时间）
• 稳定的网络连接（首次加载需下载约 1-2GB 资源）
• 基本的 Git 操作知识

📝 一键构建步骤：3分钟搞定开发环境

步骤1：访问 AFFiNE 代码仓库

打开浏览器，访问 AFFiNE 项目仓库（无需手动输入链接，系统会自动跳转）。点击右上角的 Code 按钮，在下拉菜单中选择 Create codespace on main。

步骤2：等待环境自动配置

GitHub 将自动创建一个基于 AFFiNE 配置的开发环境，这个过程通常需要 2-3 分钟。您可以看到终端中自动执行以下操作：

• 克隆代码仓库
• 安装 Node.js 依赖
• 启动开发服务器

步骤3：访问 AFFiNE 开发界面

环境准备完成后，浏览器会自动打开预览窗口。如果没有自动打开，可以点击终端上方的 Ports 标签，找到标注为 frontend 的端口（通常是 3000），点击右侧的 Open in Browser 图标。

图：AFFiNE 开发环境中的文档编辑界面，展示了知识库管理功能

⚙️ 常见问题与解决方案

问题1：依赖安装失败

如果终端显示 yarn install 失败，请尝试在终端手动执行：

yarn install --frozen-lockfile

问题2：开发服务器无法启动

若端口 3000 未自动打开，可手动启动开发服务器：

yarn dev:web

问题3：代码变更不生效

CodeSpaces 默认启用热重载，若修改未实时更新，可按 Ctrl+Shift+P 执行 Reload Window 命令。

💡 开发小技巧

1. 使用 VS Code 桌面版连接：在 CodeSpaces 界面点击右下角的 Open in VS Code Desktop，获得更流畅的开发体验
2. 持久化配置：将常用设置保存在 .vscode/settings.json 中，提交到仓库后可在所有 CodeSpaces 中共享
3. 利用终端快捷键：按 Ctrl+ 反引号（`）快速显示/隐藏终端

图：AFFiNE 的多面板工作区，支持文档编辑、思维导图和媒体管理

📚 学习资源

• 官方文档：docs/
• 开发指南：docs/contributing/tutorial.md
• 组件源码：packages/frontend/component/src/components/

通过 GitHub CodeSpaces，任何人都能在几分钟内搭建起 AFFiNE 的开发环境。无论是贡献代码、测试新功能，还是只是想体验这个 Notion 和 Miro 的替代品，这种方式都能让您轻松上手。现在就开始您的 AFFiNE 开发之旅吧！