Cal.com 本地开发环境搭建指南

Cal.com 本地开发环境搭建指南

cal.com cal.com: cal.com是一款开源的日历应用，提供了一种统一的方式来管理个人或团队的日程安排和事件，具有良好的用户体验和强大的API。 项目地址: https://gitcode.com/gh_mirrors/ca/cal.com

前言

Cal.com 是一款开源的日程安排和会议管理工具，其本地开发环境搭建相对简单。本文将详细介绍如何在本地搭建 Cal.com 的开发环境，包括环境准备、依赖安装、数据库配置以及开发模式运行等关键步骤。

环境准备

系统要求

Cal.com 对硬件要求不高，主要资源消耗发生在构建阶段，运行时相对轻量。支持的操作系统包括：

• Windows
• macOS
• Linux
• BSD

虽然所有上述系统都能运行，但生产环境推荐使用 Linux 系统。任何能运行 Node.js 的操作系统理论上都可以运行 Cal.com。

必备软件

在开始前，请确保已安装以下软件：

1. Node.js - 推荐版本 18（稳定性和兼容性最佳）
2. Yarn - 包管理工具
3. Git - 版本控制工具
4. PostgreSQL - 数据库系统

对于 Linux/BSD 用户，可以通过系统包管理器直接安装这些软件。Windows 和 macOS 用户需要单独下载安装。

项目初始化

1. 克隆代码仓库

首先需要获取项目源代码：

git clone https://github.com/calcom/cal.com.git

Windows 用户特别注意：需要使用管理员权限执行以下命令：

git clone -c core.symlinks=true https://github.com/calcom/cal.com.git

2. 安装依赖

进入项目目录并安装依赖：

cd cal.com
yarn

环境配置

1. 配置文件准备

Cal.com 使用 .env 文件进行配置：

cp .env.example .env
cp .env.appStore.example .env.appStore

.env 文件包含大量配置选项，每个选项都有详细注释说明其用途。

2. 生成安全密钥

生成 NEXTAUTH_SECRET：

openssl rand -base64 32

将生成的密钥填入 .env 文件的 NEXTAUTH_SECRET 字段。

3. 数据库配置

修改 .env 文件中的数据库连接字符串：

DATABASE_URL='postgresql://<用户名>:<密码>@<主机>:<端口>/<数据库名>'

生成加密密钥：

openssl rand -base64 24

将结果填入 CALENDSO_ENCRYPTION_KEY 字段。

数据库初始化

使用 Prisma 初始化数据库：

yarn workspace @calcom/prisma db-deploy

开发模式运行

启动开发服务器：

yarn dev

快速开发模式 (使用 Docker)

如果已安装 Docker 和 Docker Compose，可以使用快速开发模式：

yarn dx

此命令会自动启动包含测试数据的 PostgreSQL 容器，控制台会输出登录凭据。

开发技巧

调试模式

在 .env 文件中添加：

NEXT_PUBLIC_DEBUG=1

这会启用 tRPC 的所有查询和变更日志。

邮件测试

如需测试邮件功能：

echo 'E2E_TEST_MAILHOG_ENABLED=1' >> .env

确保手动运行 mailhog 容器或使用 yarn dx。

端到端测试

运行端到端测试：

yarn test-e2e

查看测试报告：

yarn playwright show-report test-results/reports/playwright-html-report

API 开发

API V1 开发

1. 复制环境文件：

cp apps/api/.env.example apps/api/v1/.env

2. 启动开发服务器：

yarn workspace @calcom/api dev

API V2 开发

注意：V2 API 需要运行在 Docker 中的数据库

1. 复制环境文件：

cp apps/api/.env.example apps/api/v2/.env

2. 启动开发服务器：

yarn workspace @calcom/api-v2 dev

Windows 用户注意：需要修改 apps/api/package.json 中的 dev 脚本：

"dev": "set PORT=3003 && next dev"

企业功能说明

在本地测试企业功能时，系统会显示警告提示，提醒在生产环境中使用这些功能需要购买许可证。

定时任务

Cal.com 的部分功能依赖定时任务，相关代码位于：

/apps/web/app/api/cron

结语

通过以上步骤，您已成功搭建 Cal.com 的本地开发环境。现在可以开始进行功能开发和测试。开发过程中，建议定期查看项目文档更新，以获取最新的开发指南和最佳实践。

cal.com cal.com: cal.com是一款开源的日历应用，提供了一种统一的方式来管理个人或团队的日程安排和事件，具有良好的用户体验和强大的API。 项目地址: https://gitcode.com/gh_mirrors/ca/cal.com