Converse.js 14.0.1 介绍与选型指南

目标：讲清 Converse.js（14.0.1，MPL-2.0）这款开源 XMPP Web 客户端库的定位、架构、功能边界与同类选型，并给出最小可用示例。全部版本与活跃度数据实查自 npm registry、GitHub Releases、shields.io 与官方 CDN（采集日期 2026-10-25），最小示例已在 Ubuntu 22.04 + Chromium 实测通过。

一、环境信息

本文涉及的事实数据采集与最小示例验证环境如下：

• 操作系统：Ubuntu 22.04（x86_64，最小示例验证机）
• Converse.js：14.0.1（2026-10-17 发布；14.0.0 发布于 2026-06-26，npm registry 共 76 个版本）
• 数据源：npm registry（converse.js 包元数据）、GitHub conversejs/converse.js Releases、shields.io 星数徽章、官方 CDN cdn.conversejs.org
• 验证浏览器：Chromium（无头模式，CDP 驱动）
• 联调服务端：Prosody IM 0.12（WebSocket 传输，仅用于验证最小示例可登录收发）

💡 说明：Converse.js 是纯前端 JavaScript 库，没有自己的服务端进程——「安装 Converse.js」就是把它的 JS/CSS 静态产物挂到任意 Web 服务器（或直接从 CDN 引用），真正提供账号、消息路由与存储的是背后的 XMPP 服务器。

二、软件概述

Converse.js 是一款开源的、运行在浏览器里的 XMPP 即时通讯客户端。它以 JavaScript 库的形态交付：在任意网页里引入一个 CSS 和一个 JS，再调用一次 converse.initialize()，页面就得到一个功能完整的 IM 客户端——单聊、多人群聊（MUC）、联系人列表、消息归档、端到端加密一应俱全。它既可以整页铺开作为一个独立的 Web 聊天站，也可以收缩成页面右下角的一个聊天控件嵌入既有站点。

项目基本信息（实查数据，采集日期 2026-10-25）：

npm 包（14.0.1）实测构成：包总体 44MB，其中 dist/ 目录约 22MB，含 converse.js（3.5MB 未压缩版）、converse.min.js（1.3MB）、converse.min.css（548KB）、按语言拆分的异步 chunk、提示音（sounds/msg_received.mp3|ogg）、字体与图片、emoji.json、多标签页共享连接用的 shared-connection-worker.js，以及 OMEMO 加密依赖的 libomemo.esm.min.js 与 curve25519_compiled.wasm。

⚠️ 注意（v14 关键变化）：14.x 的 dist 产物是原生 ES Module（产物尾部为 export{...as default}），必须用 <script type="module" src="..."> 方式加载；用传统 <script src> 加载会得到 converse is not defined。官方 quickstart 文档自 v14 起也一律使用 module 写法。

三、核心架构

理解 Converse.js 的架构，关键是分清「浏览器里的部分」和「浏览器外的部分」——它本身只有前者。

3.1 数据流与组件分层

一次典型的聊天会话数据流如下：

┌──────────────────────────── 浏览器 ────────────────────────────┐
│  Converse.js UI（Web Components）                              │
│    │                                                           │
│    ▼                                                           │
│  插件/API 层（converse.plugins.add 注册的插件，api.* 调用面）   │
│    │                                                           │
│    ▼                                                           │
│  Strophe.js 连接层（XMPP 流的建立、SASL 认证、Stanza 收发）     │
│    │                                                           │
│    ▼  本地缓存：IndexedDB / localStorage / sessionStorage       │
└────────────────────────────┬───────────────────────────────────┘
                             │ 传输层二选一：
                             │ ① WebSocket（wss://，XMPP over WebSocket，RFC 7395）
                             │ ② BOSH（https:// 长轮询，XEP-0124/0206）
┌────────────────────────────▼───────────────────────────────────┐
│                     XMPP 服务器（浏览器外）                      │
│   账号 / 花名册 / 消息路由 / 离线消息 / 归档 / 群聊（MUC 组件）    │
│   代表实现：Prosody、ejabberd、Openfire                          │
└─────────────────────────────────────────────────────────────────┘

分层职责对照：

💡 技术拓展：浏览器无法直接发起 XMPP 的 TCP 连接，所以 XMPP 为 Web 客户端定义了两种传输，同类选项对比如下——

传输	原理	特点	适用场景
WebSocket	RFC 7395，单条全双工长连接上跑 XMPP 流	延迟低、开销小、现代浏览器全支持	默认首选；Converse.js 用 websocket_url 配置
BOSH	XEP-0124/0206，HTTP 长轮询模拟双向流	兼容性最好、可穿越严格代理/老防火墙	老旧网络环境兜底，用 bosh_service_url 配置

本文及本专栏各篇实际采用 WebSocket（Prosody/ejabberd 均内置支持），理由是延迟与连接开销显著优于长轮询；仅当部署环境存在会掐断长连接的中间设备时才退回 BOSH。

3.2 「客户端库」定位的推论

这套架构带来两个直接推论：

1. 能力上限由服务端决定：消息归档（XEP-0313 MAM）、HTTP 文件上传（XEP-0363）、群聊、推送等能力都需要 XMPP 服务器端模块配合，Converse.js 只是消费方。选型时必须同时选定服务端（本专栏推荐搭配见第七节）。
2. 跨标签页共享连接：dist 中的 shared-connection-worker.js 用 SharedWorker 让同一浏览器的多个标签页复用同一条 XMPP 连接，多开页面不会重复登录挤下线。

3.3 插件机制与 API 面

Converse.js 的核心功能（群聊、通知、表情……）本身就是一组插件，对外扩展也走同一机制：用 converse.plugins.add('myplugin', {...}) 注册插件，在插件的 initialize() 里通过 this._converse.api 拿到完整 API 面（api.listen.on 事件订阅、api.send 发 Stanza、api.chats.open 打开会话、api.rooms.open 开群聊等）。

⚠️ 注意（v14 实测）：全局 converse 对象上没有 .api（只有 initialize/plugins/env 等少量成员），API 必须在自定义插件内部经 this._converse.api 获取；且自定义插件名必须列入 whitelisted_plugins 配置才会被加载。完整的插件写法与联调实录见本专栏《Converse.js 嵌入集成使用指南》篇。

四、功能特性

以下功能清单依据官方文档站与 dist 产物核对（带 ★ 的能力需要 XMPP 服务端对应模块支持）：

功能边界同样明确：

• 无音视频通话：Converse.js 不内置 Jingle（XEP-0166）音视频能力，需要音视频的场景应选 Jitsi Meet 等专用方案；
• 无独立服务端能力：没有账号注册后台、没有管理控制台（注册走 XEP-0077 带内注册表单，管理能力取决于服务端）；
• OMEMO 有生态前提：需要会话对端也用支持 OMEMO 的客户端，且依赖浏览器 WebCrypto（见第六节安全上下文限制）。

五、快速开始（最小可用示例）

最快的体验方式：不装任何东西，直接在一个 HTML 文件里从官方 CDN 引入，连接 conversejs.org 官方演示用的公共 XMPP 端点。把下面内容保存为 demo.html，经任意静态 Web 服务（或直接用浏览器打开本地文件）访问：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Converse.js 最小示例</title>
  <!-- v14 官方 CDN 推荐写法：CSS 常规引入，JS 必须 type="module" -->
  <link rel="stylesheet" href="https://cdn.conversejs.org/14.0.1/dist/converse.min.css">
  <script type="module" src="https://cdn.conversejs.org/14.0.1/dist/converse.min.js"></script>
</head>
<body>
  <script type="module">
    converse.initialize({
      websocket_url: 'wss://conversejs.org/xmpp-websocket',
      view_mode: 'fullscreen'
    });
  </script>
</body>
</html>

⚠️ 注意：CDN 路径里始终带版本号（/14.0.1/dist/）锁定版本；不带版本号的 /dist/ 路径会始终指向最新版，生产环境不建议使用。

实测验证（Chromium 无头模式加载等价页面后检查 DOM）：

converse-root=true, controlbox=true, body.class=converse-fullscreen

即 <converse-root> 自定义元素已挂载、登录控制框渲染完成、页面进入全屏模式。在此基础上把 websocket_url 换成自托管 XMPP 服务器即可投入自用——本专栏《Ubuntu 22.04 安装 Converse.js 14 指南》篇给出完整的自托管安装流程（含三个实测踩坑），《Converse.js Docker Compose 部署指南》篇给出容器化部署；与 Prosody 联调登录并实测收发消息的完整过程见《Converse.js 嵌入集成使用指南》篇（实测回显：connected, jid=admin@localhost/converse.js-32168925，消息发送与自收全部成功）。

六、适用场景与限制

6.1 适合的场景

• 给既有网站加即时通讯：论坛、社区、电商、文档站想加「站内聊」，引入两个静态资源即得完整 IM，是最省事的方案；
• 企业/团队自托管 IM 的 Web 端：与 Prosody 或 ejabberd 组合，得到一套完全自控的 Slack 替代品，Web 端免安装、零分发成本；
• 客服/旁路聊天控件：overlayed 模式在页面右下角浮出聊天窗，适合客服与社区互动入口；
• 重视开放标准与联邦：XMPP 是 IETF 标准化的开放协议，可与其他 XMPP 部署联邦互通，不被单一厂商锁定。

6.2 明确的限制

• 强依赖 XMPP 服务端：没有服务端就什么都不能跑，且多项功能（MAM 归档、文件上传、群聊）要求服务端开启对应模块；
• SCRAM 认证依赖安全上下文：登录密码认证走 SCRAM，其密钥派生使用浏览器 WebCrypto（crypto.subtle），该 API 仅在 HTTPS（或 localhost）页面可用——生产环境必须全站 HTTPS，纯 HTTP 部署会在登录时直接失败（本专栏 E1 篇有实测报错实录）；
• 无音视频通话：见第四节功能边界；
• v14 起必须 ES Module 加载：老旧的构建管线（不支持 ESM 的打包器、RequireJS 类 AMD 加载器）无法直接消费 dist 产物；
• 超大规模需掂量：单条 WebSocket 长连接模型下，在线规模上限主要取决于 XMPP 服务端的连接承载能力，而非 Converse.js 本身。

七、同类选型对比

与 Converse.js 同处「浏览器里的即时通讯客户端」定位的主要开源选项对比如下（星数为 shields.io 徽章 2026-10-25 取数，版本信息发布日实查自各仓库）：

💡 说明：上表后三者（Movim / Element Web / Chitchatter）与 Converse.js 并非同一细分物种，列入对比是因为选型时经常被一起问到。真正的同物种竞品是 JSXC 与 Candy。

选型建议（「如果…则…」）：

• 如果要把完整 IM（单聊+群聊+加密）嵌入或接入自己的网站，且认同 XMPP 开放协议→ Converse.js，它是该定位下功能最全、维护最活跃的选择；
• 如果只要一个页面右下角的轻量聊天侧栏且已运营 XMPP 服务 → 也可评估 JSXC，但其功能面与发布节奏均不及 Converse.js；
• 如果只需要一个永久在线的群聊大厅页面→ Candy 足够简单，但项目多年未更新，不建议新项目采用；
• 如果团队已选 Matrix 生态（需要 Matrix 特有的房间模型与桥接）→ Element Web，它与 XMPP 体系互不相通，属于另一条技术路线；
• 如果要零部署、聊完不留痕的临时会话→ Chitchatter（见《Chitchatter 介绍与选型指南》），它与 Converse.js 的「有账号、有归档」定位正交互补。

版本节奏与兼容性量化补充：Converse.js 在 npm 上累计发布 76 个版本，14.x 大版本线自 2026-06-26 首发、2026-10-17 发布 14.0.1，保持着活跃的大版本迭代；v14 起产物为原生 ES Module，兼容面为支持 ESM 与 WebCrypto 的所有现代浏览器（Chrome/Edge/Firefox/Safari 当前主版本），IE 等 legacy 浏览器不再支持。服务端兼容面：任何实现了 WebSocket（RFC 7395）或 BOSH 的标准 XMPP 服务器均可对接，本站已实测的组合见《Prosody IM 13.0.7 介绍与选型指南》与《ejabberd 26.09 介绍与选型指南》。

八、参考链接

• 官方网站（含演示）：https://conversejs.org/
• 官方文档站（quickstart / configuration / plugin-development）：https://conversejs.org/docs/
• 源码仓库与 Releases：https://github.com/conversejs/converse.js
• npm 包：https://www.npmjs.com/package/converse.js
• 官方 CDN（版本化路径）：https://cdn.conversejs.org/14.0.1/dist/converse.min.js
• XMPP 协议与 XEP 扩展索引：https://xmpp.org/extensions/
• MPL-2.0 许可文本：https://www.mozilla.org/en-US/MPL/2.0/

本专栏其他篇目：《Ubuntu 22.04 安装 Converse.js 14 指南》、《Converse.js Docker Compose 部署指南》、《Converse.js 14 配置参数详解》、《Converse.js 嵌入集成使用指南》。