Kiwi IRC 1.7.1 配置参数详解

目标：讲清 Kiwi IRC 1.7.1 的运行时配置体系——config.json 的加载与合并链路、全部内置默认值（逐项溯源自 v1.7.1 源码 src/res/configTemplates.js）、startupOptions / buffers 等参数组的行为、以及直连 / 网关 / BNC 三种连接形态下的配置组织。所有默认值与行为结论均为 2026-10-26 源码实查与本地实测所得。

一、环境信息

二、配置体系与加载链路

2.1 唯一的运行时配置文件

Kiwi IRC 1.7.1 的全部运行时行为由一个 JSON 配置文件驱动：源码树中为 static/config.json，构建后随 dist/ 分发（dist/static/config.json），页面加载后由前端运行时拉取（src/libs/ConfigLoader.js 的 loadFromUrl 实查）。没有独立的后端配置进程，改配置 = 改文件 + 浏览器刷新。

2.2 三层合并：内置模板 → 基础模板 → 用户配置

源码 src/libs/state.js 与 main.js 实查，最终生效的配置按以下顺序合并（后者覆盖前者）：

1. 内置默认模板：src/res/configTemplates.js 中的 default 对象——全部配置项的权威默认值都在这里（第三章起的参数表即逐项取自该文件）；
2. 基础模板覆盖：若 config.json 设置了顶层 template 键，则把 configTemplates.irc（硬核 IRC 老手风格）或 configTemplates.team（团队协作风格）合并到默认值之上；
3. 用户配置：config.json 本身最后合并——所以只需写「与默认值不同的项」。

两个官方附加模板的覆盖内容（configTemplates.js 实查）：

2.3 JSON5 语法与报错定位

配置文件用 JSON5 解析（ConfigLoader.js 实查）：支持注释与尾逗号；语法错误时报错形如 Config file error: ...，并自动把 JSON5 的 at 22:16 转写为 line 22, position 16（源码中的正则替换），可按行号列号直接定位。

2.4 值替换机制：? 变随机数

startupOptions.nick 与 nick_format 中的 ? 会被替换为 0–99 的随机整数——源码 components/startups/CustomServer.vue 实查：nick.replace(/?/g, () => Math.floor(Math.random() * 100).toString())。配置写 guest_? 时，实测连接页预填为 guest_99 一类的随机值，多开页面自然错开昵称。

2.5 配置持久化边界

src/libs/settingTools.js 实查，以下键被列为实例级配置、不会写入用户级持久化状态：emojis、themes、bnc、aliases、restricted、kiwiServer、hide_advanced、windowTitle、startupOptions、plugins、presetNetworks、ircFramework。即这些项改了只影响站点本身，不跟随单个浏览器的用户偏好走。

三、顶层参数详解

以下默认值全部取自 configTemplates.js 的 default 模板（逐项实查）。

3.1 站点外观与语言

3.2 启动与连接骨架

3.3 startupScreen：五种内置启动屏

源码 components/App.vue 实查，启动屏组件注册表为：

此外插件可通过 getStartups() 注册自定义启动屏；配错名字会在控制台报 Startup screen "xxx" does not exist 并白屏，排障时先查该值。

3.4 行为开关

四、startupOptions 参数组（连接行为）

默认值（configTemplates.js 实查）：

{
    "server": "",
    "port": 6667,
    "tls": false,
    "channel": "",
    "nick": "kiwi_?",
    "direct": false,
    "state_key": "kiwi-state",
    "remember_buffers": true,
    "nick_format": ""
}

逐项说明（含部署篇实测值对照）：

⚠️ 注意：startupOptions 直接决定用户「开箱看到什么」。restricted: true + startupScreen: "customServer" 组合是「站点即单一网络入口」的最常见形态；要开放多网络自助连接，用 restricted: false + startupScreen: "personal"。

五、buffers 参数组（消息缓冲与显示）

buffers 控制每个频道/私聊缓冲区的显示与通知行为，默认值（configTemplates.js 实查，共 37 项，分组列出）：

布局与时间戳

通知与提醒

消息可见性

行为细节

六、文本格式与别名（textFormats / aliases）

textFormats：界面消息模板集合（60+ 键），用 %nick/%text/%channel 等占位符定制每类消息的呈现。几个实测对照：部署篇频道视图中的「→ kiwibrowser has joined」正是默认模板 channel_join: "→ %text" 的渲染结果；入退频道箭头、话题 ⓘ、错误 ⚠ 前缀全部出自这里。常用键举例：

aliases：命令别名表（默认为一段多行模板字符串，configTemplates.js 实查），常用默认别名包括 /p→/part、/j→/join、/q→/query、/w→/whois、/raw→/quote、/k→/kick、/bans→/mode +b、/slap 彩蛋别名等。可在 config.json 中整体覆盖以注入站点自定义命令。

emojis：文本表情→图片文件映射表（130+ 项），配合 emojiLocation 使用；一般不动，需定制表情时在 config.json 覆盖对应键值即可。

七、三种连接形态的配置组织

配置组织建议：直连形态下端口/路径三处联动（nginx listen、startupOptions.port、direct_path）；网关形态下注意 kiwiServer 与网关路由前缀一致；BNC 形态的账号密码建议走连接页输入而非写死在配置里。

八、生产配置实测验证

以部署篇的生产配置为基准（直连形态，全文见部署篇第六章），逐项验证结果如下（2026-10-26 实测）：

九、常见配置问题（FAQ）

Q1：改了 config.json 不生效？ A：配置在页面加载时拉取，改完需浏览器强制刷新（Ctrl+Shift+R）；另确认改的是部署目录（dist/static/config.json 或站点目录对应文件），而不是源码树里的副本。

Q2：启动屏白屏？ A：startupScreen 拼错时 App.vue 会报 Startup screen "xxx" does not exist（控制台可见）。合法值：welcome/customServer/personal/kiwiBnc/znc，或插件注册的自定义名。

Q3：配置报 Config file error: JSON5 ...？ A：JSON5 语法错误会精确到行号列号（line 22, position 16 形式），按提示修复；注意 JSON5 允许注释和尾逗号，但不允许未加引号的非法标识符之外的花样。

Q4：昵称尾缀随机数能控制范围吗？ A：? 固定替换为 0–99 随机整数（源码写死 Math.floor(Math.random() * 100)），无法配置范围；需要更大区分度可用 nick_format 自定义模板或接入账号体系。

Q5：restricted 设 false 后用户能改什么？ A：放开的是网络列表/自助添加网络入口（StateBrowser 侧栏）；服务器地址锁定逻辑还受 startupScreen 形态影响，两种取值建议按 3.3 的形态表搭配使用。

Q6：template 模板与显式配置冲突听谁的？ A：合并顺序为 default 模板 → template 指定模板 → config.json，显式配置永远最后覆盖；反之模板覆盖过的项，若 config.json 没写，就以模板值为准。

Q7：direct 模式连不上而网关模式正常？ A：依次查三处：ircd 是否开了 WebSocket 监听（Ergo 为 listeners 的 websocket: true，注意其「仅 WebSocket」语义，纯 TCP 客户端连该口会得 400）、nginx 反代段是否带 Upgrade/Connection 头、startupOptions.port 是否指向 nginx 而非 ircd 端口。

十、参考链接与站内文档

• Kiwi IRC 仓库：https://github.com/kiwiirc/kiwiirc
• 配置 wiki：https://github.com/kiwiirc/kiwiirc/wiki/Configuration
• 插件 wiki：https://github.com/kiwiirc/kiwiirc/wiki/Plugins
• v1.7.1 源码 configTemplates.js（本文默认值溯源处）：https://github.com/kiwiirc/kiwiirc/blob/v1.7.1/src/res/configTemplates.js
• webircgateway：https://github.com/kiwiirc/webircgateway
• KiwiBNC：https://github.com/kiwiirc/kiwibnc

站内相关文档：

• 《Kiwi IRC 1.7.1 介绍与选型指南》
• 《Debian 12 部署 Kiwi IRC 1.7.1 指南》