Ubuntu 22.04 安装 Converse.js 14 指南

目标：在 Ubuntu 22.04 上从零安装 Converse.js 14.0.1，给出「npm 下载 + Nginx 自托管」「npm 离线包」「官方 CDN 直引」三种方案，含 ES Module 加载、emoji 404、wasm MIME 三个实测踩坑的完整排障过程。已在 Ubuntu 22.04（nginx/1.18.0、Node.js v22.23.4）实测通过。

一、环境信息

本文所有命令与回显均在以下实测环境中执行：

• 操作系统：Ubuntu 22.04（x86_64）
• Web 服务器：nginx/1.18.0（Ubuntu apt 仓库）
• Node.js：v22.23.4 / npm 10.9.9（NodeSource setup_22.x 仓库）
• Converse.js：14.0.1（npm 包 converse.js，2026-10-17 发布）
• 部署路径：/var/www/conversejs/（站点根）、/var/www/conversejs/dist/（Converse.js 产物）
• 验证浏览器：Chromium（无头模式，CDP 驱动检查 DOM 状态）

💡 说明：Converse.js 是纯前端库，「安装」的本质是拿到它的 dist 静态产物并用 Web 服务器托管（或直接从 CDN 引用）。Node.js/npm 在这里只是下载产物的工具，运行时不需要 Node 进程。

二、前置条件

1. 一台 Ubuntu 22.04 服务器，具备 root 或 sudo 权限；
2. 一个可连接的 XMPP 服务器 WebSocket/BOSH 端点——本文示例使用 conversejs.org 官方公共端点 wss://conversejs.org/xmpp-websocket 做最小验证，生产环境对接自建服务端（搭建方法见《Ubuntu 22.04 安装 Prosody IM 13.0.7 指南》）；
3. 生产环境必须为站点配置 HTTPS：Converse.js 的 SCRAM 密码认证依赖浏览器 WebCrypto API，该 API 在非 HTTPS（且非 localhost）页面被禁用，登录会直接失败（实测报错实录见本专栏《Converse.js 嵌入集成使用指南》篇的踩坑章节）。

三、版本选型说明

Converse.js 在 npm registry 累计发布 76 个版本，14.x 为当前大版本线：

可用 npm view converse.js versions / npm view converse.js time 随时查询最新版本与发布时间。本文所有方案锁定 14.0.1。

⚠️ 注意：v14 起 dist 产物是原生 ES Module，必须 <script type="module"> 加载，这是与老版本最大的使用差异，踩坑实录见九、9.1。

四、方案 A：npm 下载 + Nginx 自托管（推荐）

4.1 方案说明

官方推荐的两种使用形态是「npm 包自托管」与「CDN 直引」，本方案是前者：用 npm 拉取 converse.js 包，把其中的 dist/ 目录交给 Nginx 托管。优点是产物完全自控、可离线分发、可锁版本；代价是要维护一份静态文件。

4.2 安装 Nginx

apt-get update
apt-get install -y nginx

验证版本：

nginx -v

实测回显：

nginx version: nginx/1.18.0 (Ubuntu)

4.3 安装 Node.js 22（NodeSource 仓库）

Ubuntu 22.04 自带仓库的 Node.js 版本过老，用 NodeSource 官方仓库安装 22.x LTS：

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

验证：

node -v
npm -v

实测回显：

v22.23.4

10.9.9

4.4 下载 Converse.js 14.0.1 并部署 dist

新建一个构建目录，用 npm 拉取指定版本：

mkdir -p /opt/conversejs-build
cd /opt/conversejs-build
npm install converse.js@14.0.1 --no-audit --no-fund

实测回显：

added 31 packages in 29s

💡 说明：安装过程中会出现一条 npm warn deprecated core-js 弃用告警，来自 Converse.js 构建链的传递依赖，不影响产物使用，可忽略。若服务器访问 npm 官方源缓慢，可先执行 npm config set registry https://registry.npmmirror.com 切换国内镜像再安装；本文实测官方源直连可用。

把包内的 dist/ 目录整体部署到站点目录（必须保持 /dist/ 子路径，原因见九、9.2）：

mkdir -p /var/www/conversejs
cp -r /opt/conversejs-build/node_modules/converse.js/dist /var/www/conversejs/dist
du -sh /var/www/conversejs/dist

实测回显：

22M	/var/www/conversejs/dist

4.5 编写站点首页

创建 /var/www/conversejs/index.html：

<!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>
  <!-- 关键：dist 挂在 /dist/ 子路径；JS 必须 type="module" -->
  <link rel="stylesheet" href="/dist/converse.min.css">
  <script type="module" src="/dist/converse.min.js"></script>
</head>
<body>
  <script type="module">
    converse.initialize({
      websocket_url: "wss://conversejs.org/xmpp-websocket",
      view_mode: "fullscreen",
      authentication: "login",
      allow_registration: true,
      i18n: "zh_CN",
      play_sounds: true,
      show_controlbox_by_default: true
    });
  </script>
</body>
</html>

关键初始化项说明：websocket_url 是 XMPP 服务器的 WebSocket 端点（示例为官方公共端点，生产换成自建服务端地址）；view_mode: fullscreen 让 Converse.js 铺满整页；i18n: zh_CN 切换简体中文界面。全部 153 个配置项见本专栏《Converse.js 14 配置参数详解》篇。

4.6 配置 Nginx 站点

创建 /etc/nginx/sites-available/conversejs：

server {
    listen 80;
    server_name _;
    root /var/www/conversejs;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    # 静态资源缓存 7 天（dist 内容按版本目录更新，可安全长缓存）
    location ~* \.(js|css|woff2?|mp3|ogg|png|svg|ico|json|wasm)$ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

修正 nginx 1.18 缺失的 wasm MIME 类型（否则 OMEMO 加密组件加载有告警，原理见九、9.3）：编辑 /etc/nginx/mime.types，在 types { 块内首行加入：

    application/wasm wasm;

启用站点并重载：

ln -s /etc/nginx/sites-available/conversejs /etc/nginx/sites-enabled/conversejs
nginx -t

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

4.7 systemd 托管与启动

Nginx 安装后自带 systemd 单元，逐条执行：

systemctl enable nginx
systemctl restart nginx
systemctl is-active nginx

实测回显：

active

4.8 验证

首页与关键静态资源逐个验证：

curl -sI http://127.0.0.1/

实测回显：

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Content-Type: text/html

curl -sI http://127.0.0.1/dist/converse.min.js

实测回显：

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Content-Type: application/javascript
Content-Length: 1308228

curl -sI http://127.0.0.1/dist/curve25519_compiled.wasm | grep -i content-type

实测回显（9.3 修复生效后）：

Content-Type: application/wasm

浏览器侧最终验证（Chromium 加载页面后检查 DOM）：<converse-root> 已挂载、登录控制框渲染、全屏模式生效——

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

浏览器打开 http://<服务器IP>/ 即可看到中文登录界面，输入任意 conversejs.org 账号即可登录体验；对接自建服务端的端到端收发实测见本专栏《Converse.js 嵌入集成使用指南》篇。

五、方案 B：npm 离线包安装（内网/断网）

5.1 方案说明

目标服务器不能联网时，在一台可联网的机器上把 npm 包打成 tarball，拷贝到目标服务器解压部署。产物与方案 A 完全一致，Nginx 配置也复用 4.6。

5.2 联网机器上打包

npm pack converse.js@14.0.1 --no-audit --no-fund

实测回显（摘要）：

npm notice Tarball Details
npm notice name: converse.js
npm notice version: 14.0.1
npm notice filename: converse.js-14.0.1.tgz
npm notice package size: 8.0 MB
npm notice unpacked size: 38.7 MB
npm notice shasum: f7c4933458136daedbe0a1376ed63ca642f3495b
npm notice total files: 1881

得到 converse.js-14.0.1.tgz（实测 7.7MB），用 scp/U 盘等方式拷贝到目标服务器，建议同时记下上面的 shasum 以便核对完整性。

5.3 目标服务器解压部署

mkdir -p /opt/conversejs-build
tar -xzf converse.js-14.0.1.tgz -C /opt/conversejs-build
mkdir -p /var/www/conversejs
cp -r /opt/conversejs-build/package/dist /var/www/conversejs/dist

压缩包内顶层目录固定为 package/，解压后 dist 位于 package/dist。随后按 4.5 编写首页、按 4.6/4.7 配置并启动 Nginx，验证方式与实测回显同 4.8。

六、方案 C：官方 CDN 直引（零安装）

不部署任何文件，页面直接从官方 CDN 加载指定版本：

<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>

替换 4.5 首页中的两行引用即可，初始化代码不变。本文实测 CDN 资源可达：https://cdn.conversejs.org/14.0.1/dist/converse.min.js 返回 HTTP 200（Server: keycdn）。浏览器侧验证回显同样为 converse-root=true, controlbox=true, body.class=converse-fullscreen。

⚠️ 注意：CDN 路径务必带版本号锁定；不带版本号的 /dist/ 路径始终指向最新版，生产环境版本漂移风险自负。CDN 方案意味着页面可用性依赖第三方 CDN 与访客网络，内网/合规场景应选方案 A 或 B。

七、方案对比与选择建议

选择建议：生产环境默认选 A；目标机器不能联网选 B（与 A 产物相同，只是转运方式不同）；临时体验或给已有页面快速挂聊天选 C。

八、配置说明

安装完成后最常调整的配置集中在两处：

1. Nginx 站点配置（/etc/nginx/sites-available/conversejs）：监听端口、server_name、静态缓存周期。生产上线时把 listen 80 改为 443 并配置证书（HTTPS 必要性见二、前置条件）。
2. 初始化参数（index.html 中 converse.initialize({...})）：常用项速查——

逐项详解（153 项全量）见本专栏《Converse.js 14 配置参数详解》篇。

九、常见问题（FAQ）

9.1 页面空白，控制台 converse is not defined，<converse-root> 不出现

现象：用传统 <script src="/converse.min.js"></script> 加载 v14 产物后，页面无任何聊天界面，浏览器检查 DOM 无 converse-root 元素，typeof converse 为 undefined。

定位：v14 的 dist 是原生 ES Module（产物尾部为 export{...as default}），普通 script 标签加载时模块不会执行顶层导出绑定，全局 converse 不会被注册。

解决：改为模块方式加载——

<script type="module" src="/dist/converse.min.js"></script>

页面内调用 converse.initialize(...) 的内联脚本同样使用 <script type="module">。修复后实测 DOM 状态：converse-root=true, controlbox=true, body.class=converse-fullscreen。官方 quickstart 自 v14 起也一律是 module 写法。

9.2 控制台报 Failed to load emoji.json，表情面板空白

现象：把 dist/ 目录里的内容直接平铺到站点根（即 /converse.min.js 而非 /dist/converse.min.js）后，控制台出现 Failed to load emoji.json，emoji 选择器无数据。

定位：Converse.js 的异步资源（语言 chunk、emoji.json、提示音、字体）按 assets_path 配置加载，默认值为 /dist/。平铺部署后它仍去 /dist/emoji.json 取文件，自然 404。

解决（二选一）：

• 推荐：保持本文方案的目录结构，dist 整体挂在站点 /dist/ 子路径下，与默认 assets_path 一致；
• 必须平铺时，在 converse.initialize({...}) 中显式设置 assets_path: '/'（或实际子路径）。

9.3 控制台告警 wasm streaming compile failed

现象：页面功能基本正常，但控制台出现 WebAssembly 流式编译失败告警，涉及 curve25519_compiled.wasm（OMEMO 加密的曲线计算组件）。

定位：nginx 1.18 的 /etc/nginx/mime.types 未收录 wasm 类型，实测响应该文件时 Content-Type: application/octet-stream，浏览器因此拒绝流式编译（会自动降级为 ArrayBuffer 编译，功能可用但有性能损失与告警噪音）。

解决：按 4.6 在 mime.types 的 types { 块内加入 application/wasm wasm;，执行 nginx -t 通过后 systemctl reload nginx。实测修复后响应头为 Content-Type: application/wasm，告警消失。

9.4 登录时控制台 TypeError: Failed to fetch，始终停在登录页

现象：初始化参数已填 websocket_url，但提交登录后控制台报 Failed to fetch，无法登录。

定位：discover_connection_methods 默认为 true，Converse.js 会按 XEP-0156 先请求 https://<JID域名>/.well-known/host-meta 自动发现连接端点；当 JID 域名不可解析（如内网域名、localhost）或该地址无 HTTPS 服务时，发现请求直接抛错并阻断登录流程。

解决：初始化时显式关闭发现，或让 XMPP 域名可解析并正确部署 host-meta——

converse.initialize({
  websocket_url: "wss://xmpp.example.com/xmpp-websocket",
  discover_connection_methods: false
});

该问题的完整联调实录（含 WebSocket 握手 101 验证）见本专栏《Converse.js 嵌入集成使用指南》篇。

十、卸载与清理

Converse.js 全部交付物就是 /var/www/conversejs 下的静态文件与构建目录，卸载即删除：

rm -rf /var/www/conversejs
rm -rf /opt/conversejs-build
rm -f /etc/nginx/sites-enabled/conversejs
rm -f /etc/nginx/sites-available/conversejs
nginx -t
systemctl reload nginx

若该机不再运行其他站点与 Node 工作负载，可一并移除：

apt-get purge -y nginx nginx-common
apt-get purge -y nodejs
rm -f /etc/apt/sources.list.d/nodesource.list

十一、参考链接

• 官方 Quickstart（v14 module 写法）：https://conversejs.org/docs/html/quickstart.html
• 官方配置项文档：https://conversejs.org/docs/html/configuration.html
• npm 包版本与发布时间：https://www.npmjs.com/package/converse.js
• NodeSource Node.js 仓库：https://github.com/nodesource/distributions
• XMPP over WebSocket（RFC 7395）：https://www.rfc-editor.org/rfc/rfc7395
• XEP-0156 连接方法发现：https://xmpp.org/extensions/xep-0156.html

本专栏其他篇目：《Converse.js 介绍与选型指南》、《Converse.js Docker Compose 部署指南》、《Converse.js 14 配置参数详解》、《Converse.js 嵌入集成使用指南》。