evolution-api

一行代码接入 WhatsApp，快速构建聊天机器人和客服系统

Evolution API 是一个开源的 WhatsApp 集成 API 服务，基于 TypeScript 构建，旨在为开发者提供稳定、可扩展的 WhatsApp 云 API 替代方案。它解决了企业或个人开发者难以直接接入 WhatsApp 官方 API 的痛点，通过 RESTful 接口和 WebSocket 支持，让开发者能够快速实现消息收发、群组管理、媒体传输等核心功能。项目内置了多实例管理、消息队列（RabbitMQ）、实时推送（Pusher）等机制，支持与 Chatwoot、Dify、Typebot、n8n 等主流平台无缝集成，可轻松构建聊天机器人、客服系统、自动化营销等场景。其活跃的社区和持续更新使其成为 WhatsApp 生态中极具潜力的开源工具。

开源 unknown 对话助手

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 9669

维护状态维护中

是否开源是

定价模式 unknown

项目数据

分类对话助手

开发团队evolution-foundation

所属国家

官网地址https://evolutionfoundation.com.br

GitHubhttps://github.com/evolution-foundation/evolution-api

定价模式unknown

价格说明开源项目，官网未明确展示定价信息，需进一步确认。

访问状态

是否开源是

开源协议NOASSERTION

主要语言TypeScript

技术栈/模型chatbot,chatwoot,cloud-api,dify,evolution,n8n,openai,pusher,rabbitmq,typebot,whatsapp,whatsapp-api,whatsapp-bot

GitHub 星标★ 9669

30天Star增速

HF 下载量

上线时间2023-06-09 00:00:00

最近更新2026-09-22 00:00:00

维护状态维护中

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数6

使用教程

难度：进阶约 20 分钟部署方式：Docker 6 步

环境要求

Node.js 与 npm 环境（用于执行 npm install / build / start:prod）
一个可连接的数据库（README 提到执行 migrations，未指明具体数据库类型）
Docker（如使用官方镜像部署方式）
可访问 GitHub 与 npm 源 / Docker Hub 的网络环境

安装与启动步骤

1克隆项目仓库

README 使用的是 SSH 地址，需本机已配置 GitHub SSH 密钥，克隆后进入项目目录。
```
git clone git@github.com:evolution-foundation/evolution-api.git
cd evolution-api
```
2安装依赖

在项目根目录执行，安装 package.json 中声明的全部依赖。
```
npm install
```
3准备环境变量文件

README 的 Docker 命令通过 --env-file .env 读取配置，需先在项目根目录准备好 .env 文件，具体变量见官方文档。
4执行数据库迁移

README 的 Database setup 步骤，通过 npm 脚本部署数据库结构，需数据库已可连接。
```
npm run db:deploy
```
5构建并启动服务

README 的生产运行方式：先构建，再以 prod 模式启动服务。
```
npm run build
npm run start:prod
```

6或用 Docker 部署

拉取官方镜像并以 8080 端口启动，配置由 .env 文件注入。

docker pull evoapicloud/evolution-api:latest
docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latest

关键配置

配置项	必填	说明	示例
`.env`	是	Docker 启动时通过 --env-file 注入的环境变量文件，具体变量项 README 未列出	`/your/path/evolution-api/.env`

如何确认成功

服务启动后监听 8080 端口（镜像映射 -p 8080:8080），可访问 http://localhost:8080 确认接口可用。

常见问题

Q：不用 Docker 可以在本地跑吗？

A：可以。README 给出了 npm 方式：npm install 安装依赖、npm run db:deploy 部署数据库迁移、npm run build 构建、npm run start:prod 生产模式启动。

Q：git clone 报权限错误怎么办？

A：README 中的地址为 SSH 形式 git@github.com:..., 需要本机已配置可用的 GitHub SSH 密钥，否则无法拉取。

Q：npm run db:deploy 失败怎么办？

A：该命令用于部署数据库迁移，需数据库已启动且连接信息正确写入配置文件；README 未列出具体数据库类型和变量，请参考官方文档 docs.evolutionfoundation.com.br。

Q：Docker 启动后无法连接数据库怎么排查？

A：确认 .env 已存在且随 --env-file 挂载，容器内的连接地址需指向容器可访问的数据库主机，而非 localhost。

注意事项

README 仅给出快速开始命令，完整配置项请查阅官方文档 https://docs.evolutionfoundation.com.br
Docker 方式默认映射宿主 8080 端口，如被占用需调整端口映射
生产环境运行需先执行构建，不要遗漏 npm run build
官方镜像为 evoapicloud/evolution-api:latest，社区与支持入口见 evolutionfoundation.com.br

核心亮点

提供完整的 REST API 和 WebSocket 支持，消息收发、媒体传输开箱即用
支持多实例隔离，配合 RabbitMQ 和 Redis 可水平扩展，适合生产环境
与 Chatwoot、Dify、n8n 等流行工具深度集成，降低自动化流程搭建门槛

不足之处

依赖 WhatsApp 非官方协议，存在账号被限制的风险
部署配置相对复杂，需要管理数据库、队列等外部依赖
文档/社区待观察

适用场景

企业客服系统接入 WhatsApp 渠道，统一管理客户对话
基于 WhatsApp 的营销自动化，如群发通知、自动回复
结合 AI 平台（如 Dify）构建智能聊天机器人

替代项目

WhatsApp Business API、Baileys、whatsapp-web.js

项目介绍

evolution-api 是对话助手领域的开源项目，由 evolution-foundation 开发，2023 年首次发布。

在全站 13,014 个收录项目中，它的 GitHub 星标数（9,669）位列前 6%，在对话助手分类的 905 个项目里位列前 3%。

近 44 天，它的 GitHub 星标从 9,247 增加到 9,669，净增 422。

项目仍在小幅维护中，最近一次代码更新于 2026-09-22。官网未明确展示定价信息，需进一步确认。从国内网络环境看，可直接访问。

它主要面向的使用场景是：企业客服系统接入WhatsApp渠道，统一管理客户对话。同类可对比的替代方案包括 WhatsApp Business API、Baileys、whatsapp-web.js。

上一篇：typebot.io

下一篇：node-telegram-bot-api