Converse.js 14.0.1 配置参数详解

目标：逐项讲清 Converse.js 14.0.1 全部 153 个初始化配置项（converse.initialize({...}) 的入参）——默认值、类型、取值范围与使用场景，按 11 个功能域分组，附三套生产配置模板与高频踩坑。配置项清单实查自官方 configuration 文档（2026-10-25），关键项已在 Ubuntu 22.04 自托管实例 + Chromium 实测验证。

一、环境信息

• Converse.js：14.0.1（npm 包 converse.js，2026-10-17 发布）
• 参数来源：官方配置文档 conversejs.org/docs/html/configuration.html（2026-10-25 采集，共 153 项）
• 验证环境：Ubuntu 22.04（x86_64）+ nginx/1.18.0 自托管 dist（安装方法见本专栏《Ubuntu 22.04 安装 Converse.js 14 指南》），Chromium 无头模式实测
• 联调服务端：Prosody IM 0.12（WebSocket 传输）

二、前置条件

1. 已完成 Converse.js 14.0.1 的部署（自托管或 CDN，方法见本专栏安装与部署篇目）；
2. 能修改承载页面的 HTML/JS——Converse.js 没有服务端配置文件，全部配置都是页面侧 JS 对象；
3. 一个可连接的 XMPP 服务器端点（本文示例用 wss://conversejs.org/xmpp-websocket 公共端点与自托管 Prosody 端点）。

三、参数查看与修改方式

Converse.js 是浏览器端库，配置只有「初始化入参」一个来源，有三种等价写法：

方式 1（最常用）：converse.initialize() 传对象

converse.initialize({
  websocket_url: "wss://conversejs.org/xmpp-websocket",
  view_mode: "fullscreen",
  i18n: "zh_CN"
});

方式 2：外部 config.js 注入（推荐生产使用）

页面先加载 /config.js（定义 window.CONVERSE_CONFIG 对象），初始化时透传，改配置不动页面代码：

converse.initialize(window.CONVERSE_CONFIG || {});

方式 3：URL 片段临时调日志级别

个别参数支持 URL 覆盖用于现场调试，如 https://<站点>/#converse?loglevel=debug 临时把 loglevel 提到 debug，刷新即生效、不影响其他访客。

查看生效值：浏览器控制台经插件 API 读取（api.settings.get('websocket_url') 等，插件写法见本专栏《Converse.js 嵌入集成使用指南》篇）。

⚠️ 注意：配置必须在 converse.initialize() 调用之前就位。initialize 之后再改 window.CONVERSE_CONFIG 或全局变量不会生效，必须重新初始化（刷新页面）。

四、参数总览

153 个参数按功能域分为 11 组：

五、核心参数分类详解

5.1 连接与传输

关键项示例（对接自托管服务端、关发现、开自动重连）：

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

5.2 认证与账号

💡 技术拓展：四种认证方式对应四类部署形态——

方式	用户输入	典型场景
login	JID + 密码	默认表单登录，独立 IM 站
external	无（外部会话）	已登录业务系统后免密进入
anonymous	无	访客临时聊天（需服务端开匿名域）
prebind	无	后端先与 XMPP 建会话再交给前端，单点登录体验最好

本文示例与专栏各篇默认用 login；给既有系统做嵌入且要免登录时选 prebind（需后端配合，见本专栏《Converse.js 嵌入集成使用指南》篇）。

5.3 视图与界面

三种 view_mode 的实测差异与嵌入示例见本专栏《Converse.js 嵌入集成使用指南》篇。

5.4 联系人与在线状态

5.5 消息行为

5.6 媒体渲染与链接处理

内网部署收紧示例（只渲染本站媒体）：

converse.initialize({
  allowed_image_domains: ["im.example.com"],
  allowed_audio_domains: ["im.example.com"],
  allowed_video_domains: ["im.example.com"],
  embed_3rd_party_media_players: false
});

5.7 表情

5.8 群聊 MUC

常用群聊初始化示例：

converse.initialize({
  muc_domain: "conference.example.com",
  locked_muc_domain: true,
  auto_join_rooms: ["lobby@conference.example.com"],
  muc_nickname_from_jid: true
});

5.9 历史归档与本地存储

💡 技术拓展：三种 persistent_store 的取舍——IndexedDB 容量大、异步不阻塞 UI，是默认；localStorage 兼容性最老但容量小且同步阻塞；sessionStorage 关标签即清，适合「公用电脑不留痕」场景。

5.10 通知与声音

5.11 插件扩展与高级

六、生产配置模板

6.1 企业内网自托管（对接内网 Prosody/ejabberd）

适用：公司内网 IM，静态资源托管在一台 2C4G 的 Nginx 服务器即可（Converse.js 自身几乎零资源消耗），账号体系收敛到内网 XMPP 服务器：

converse.initialize({
  websocket_url: "wss://im.internal.example.com/xmpp-websocket",
  discover_connection_methods: false,   // 内网域名不可被公共解析，必须关
  locked_domain: "internal.example.com",
  muc_domain: "conference.internal.example.com",
  locked_muc_domain: true,
  allow_registration: false,            // 账号由管理员在服务端开通
  auto_reconnect: true,
  i18n: "zh_CN",
  view_mode: "fullscreen",
  allow_non_roster_messaging: false,
  show_desktop_notifications: true,
  play_sounds: true
});

6.2 公共社区聊天站（开放注册）

适用：面向访客的公开社区，允许自助注册、自动发现端点：

converse.initialize({
  websocket_url: "wss://im.example.com/xmpp-websocket",
  authentication: "login",
  allow_registration: true,
  registration_domain: "example.com",
  discover_connection_methods: true,
  view_mode: "fullscreen",
  i18n: "zh_CN",
  auto_reconnect: true,
  message_archiving: "im.example.com",   // 服务端已启用 MAM
  allow_message_corrections: "all",
  send_chat_markers: ["received", "displayed"]
});

6.3 嵌入既有网站的客服/社区浮窗

适用：把聊天嵌入产品页右下角，一次只开一个会话、不打扰页面路由：

converse.initialize({
  websocket_url: "wss://im.example.com/xmpp-websocket",
  view_mode: "overlayed",
  singleton: true,
  allow_url_history_change: false,       // 不动宿主页面地址栏
  locked_domain: "example.com",
  allow_registration: false,
  hide_offline_users: true,
  show_controlbox_by_default: false,
  i18n: "zh_CN"
});

⚠️ 注意：三套模板都以 HTTPS 端点为前提——wss:// 与页面 HTTPS 缺一不可，SCRAM 认证在非安全上下文会直接失败（见七、7.5）。

七、常见问题（FAQ）

7.1 改了配置但不生效

按序排查：① 配置必须在 converse.initialize() 调用之前定义完成——用外部 config.js 时确认它先于初始化内联脚本加载；② 若用静态服务器 7 天缓存策略托管了 .js（含 config.js），浏览器可能拿到旧缓存，硬刷新（Ctrl+F5）验证；③ 确认改的是实际被访问的页面文件。

7.2 登录时 TypeError: Failed to fetch，无法提交

discover_connection_methods 默认为 true，初始化或登录时会先请求 https://<JID域名>/.well-known/host-meta 做 XEP-0156 端点发现；JID 域名不可解析（内网域名、localhost）或该地址无 HTTPS 服务时请求失败并阻断登录。解决：显式配置 websocket_url 并置 discover_connection_methods: false。实测案例（含 WebSocket 握手 101 验证）见本专栏《Converse.js 嵌入集成使用指南》篇。

7.3 自定义插件的 initialize() 不执行

v14 实测：自定义插件名必须列入 whitelisted_plugins 才会被加载——

converse.plugins.add('myplugin', {
  initialize() {
    const api = this._converse.api;   // v14 的 API 面从这里取
    api.listen.on('connected', () => console.log('connected'));
  }
});
converse.initialize({
  websocket_url: "wss://im.example.com/xmpp-websocket",
  whitelisted_plugins: ['myplugin']
});

另注意 v14 全局 converse 对象上没有 .api，API 只能在插件内部经 this._converse.api 获取。

7.4 表情面板空白、语言不切换，控制台 Failed to load emoji.json

异步资源按 assets_path（默认 /dist/）加载。把 dist 内容平铺到站点根会导致 /dist/emoji.json 404。保持 /dist/ 子路径部署，或显式设置 assets_path 为实际路径。语言包 chunk 同理（i18n: "zh_CN" 生效前提是语言 chunk 可加载）。

7.5 HTTP 站点登录直接失败

SCRAM 密码认证的密钥派生走浏览器 WebCrypto（crypto.subtle），该 API 只在安全上下文（HTTPS、localhost、127.0.0.1）可用。实测在非安全上下文登录报 Cannot read properties of undefined (reading 'deriveBits')，SASL 失败。生产必须全站 HTTPS（页面与 wss:// 端点）；仅本机测试可临时用 http://localhost。

7.6 如何现场抓登录/收发日志

不重发版本即可提日志级别：地址栏追加 #converse?loglevel=debug 刷新（等价于 loglevel: 'debug'），Stanza 收发、SASL 流程会打进浏览器控制台；配合服务端日志（如 Prosody 的 Authenticated as ...）即可两端对照定位。

八、参考链接

• 官方配置项文档（本文 153 项来源）：https://conversejs.org/docs/html/configuration.html
• 官方插件开发文档（whitelisted_plugins / this._converse.api）：https://conversejs.org/docs/html/plugin_development.html
• XEP-0156 连接端点发现：https://xmpp.org/extensions/xep-0156.html
• XEP-0313 消息归档（MAM）：https://xmpp.org/extensions/xep-0313.html
• XEP-0198 流管理：https://xmpp.org/extensions/xep-0198.html

本专栏其他篇目：《Converse.js 介绍与选型指南》、《Ubuntu 22.04 安装 Converse.js 14 指南》、《Converse.js Docker Compose 部署指南》、《Converse.js 嵌入集成使用指南》。