Midday项目本地开发环境搭建指南

项目概述

Midday是一个开源项目，旨在提供财务管理解决方案。该项目采用现代技术栈构建，包含多个子应用模块，如网站前端(dashboard)、API服务等，并集成了多种第三方服务如Supabase、Plaid等。

环境准备

基础工具安装

1. Bun运行时：Midday项目使用Bun作为JavaScript运行时，需先安装Bun包管理器
2. Supabase CLI：用于本地Supabase服务的启动和管理
3. Docker：Supabase依赖Docker容器运行PostgreSQL数据库和其他服务

项目依赖安装

克隆项目仓库后，在项目根目录执行：

bun install

环境变量配置

项目包含多个环境变量配置文件，分布在不同的子应用目录中：

1. API服务配置 (apps/api/.env)

   • 需要配置Google OAuth凭证
   • Supabase项目ID(本地开发通常设为"local")
   • 其他第三方服务API密钥

2. Dashboard配置 (apps/dashboard/.env)

   • 需配置多种服务密钥(如Sentry、Trigger.dev等)
   • 非必要服务(如Plaid、GoCardless)可暂时不配置

3. 网站配置 (apps/website/.env)

   • 需配置各集成服务的API密钥

本地服务启动

1. Supabase服务：项目已包含Supabase配置，直接运行会自动初始化

   bun dev
   

   首次运行会：

   • 拉取必要的Docker镜像
   • 启动Supabase容器
   • 执行数据库迁移和种子脚本

2. 应用访问：

   • 网站前端：localhost:3000
   • Dashboard：localhost:3001
   • Supabase管理界面：终端输出的指定端口

常见问题解决

认证相关问题

1. OAuth配置：

   • 需要在Google Cloud平台创建OAuth凭证
   • 回调URL设置为Supabase本地认证回调地址(启动时终端会显示)

2. 用户团队视图错误：可能是Supabase本地数据库与前端预期结构不匹配导致

第三方服务集成

1. Plaid连接问题：需要有效的Plaid开发者账户和正确配置

   • 确保Plaid环境变量正确设置
   • 检查Plaid SDK初始化是否正确

2. Sentry错误：可暂时注释相关代码避免DSN密钥验证问题

项目演进方向

开发团队正在将项目迁移至Drizzle ORM，这将改善数据库操作体验并简化本地开发配置。未来版本会提供更完善的文档支持。

开发建议

1. 初次尝试可先跳过非核心功能集成(如银行连接)
2. 关注终端输出，包含重要服务信息和访问地址
3. 遇到问题时检查各服务的日志输出

通过以上步骤，开发者可以建立起基本的Midday本地开发环境，进行功能开发和调试。随着项目的演进，开发体验和文档支持将不断完善。