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

Chainlit是一个开源的Python框架，用于快速构建和部署AI应用界面。本文将详细介绍如何在本地搭建Chainlit的开发环境，包括前后端的配置与运行方法。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

1. Python环境：需要Python 3.10或更高版本
2. 包管理工具：Poetry（Python依赖管理）
3. 前端工具链：
   • NodeJS 16或更高版本
   • pnpm（替代npm的包管理工具）

对于Windows用户，需要注意pnpm脚本执行可能需要额外配置bash环境。

项目初始化

1. 获取项目代码

建议通过以下方式获取项目代码并设置远程仓库关联：

1. 创建项目分支（Fork操作）
2. 克隆你的分支到本地
3. 添加主仓库为上游远程源

这样设置后，你可以方便地同步主仓库的更新到你的本地分支。

2. 依赖安装

Chainlit项目采用前后端分离的架构，需要分别安装依赖：

# 进入后端目录
cd backend

# 使用Poetry安装Python依赖（包括开发、测试等额外依赖）
poetry install --with tests --with mypy --with dev

后端服务启动

Chainlit的后端基于Python构建，使用Poetry管理依赖。启动步骤如下：

1. 进入后端目录并激活Poetry虚拟环境
2. 运行示例程序

cd backend
poetry shell  # 激活虚拟环境
chainlit run chainlit/hello.py  # 运行示例程序

服务启动后，默认会监听8000端口，可以通过浏览器访问http://127.0.0.1:8000查看效果。

前端开发模式

Chainlit的前端基于现代JavaScript框架构建，开发时可以采用热重载模式：

1. 首先确保后端服务正在运行（可添加-h参数以无头模式运行）
2. 启动前端开发服务器

cd frontend
pnpm run dev --port 5174 --host

前端开发服务器默认使用5174端口，访问http://localhost:5174/即可连接到本地后端服务。

测试执行

Chainlit提供了完善的测试套件，包括单元测试和端到端测试。

后端单元测试

cd backend
pytest

端到端测试(E2E)

端到端测试会模拟用户操作，测试前后端的完整交互：

pnpm test

测试调试技巧

1. 运行单个测试：通过SINGLE_TEST环境变量指定测试目录

   SINGLE_TEST=scoped_elements pnpm test
   

2. 可视化调试：使用--headed参数显示浏览器窗口

   CYPRESS_OPTIONS='--headed --no-exit' pnpm test
   

开发建议

1. 在提交代码前，建议本地运行完整测试套件
2. 前端代码修改后，需要重新构建才能使后端使用最新前端资源
3. 保持开发环境与CI环境的一致性，避免出现"在我机器上能运行"的问题

通过以上步骤，你已经成功搭建了Chainlit的本地开发环境，可以开始进行功能开发和问题修复了。