3. EMQX配置文件与启动参数
EMQX 的配置体系并不是“一个文件说了算”。同一项参数，可能同时出现在 emqx.conf、容器环境变量、命令行启动参数里。如果不知道谁覆盖谁，就会出现“明明改了配置文件却不生效”的典型问题。本节先讲清三者的优先级关系，再落到核心配置项的修改与热重载操作。
一、三层配置来源与优先级
EMQX 5.x 的配置来源可以理解为三层，优先级由低到高依次为：
- 配置文件
emqx.conf：持久化的基础配置，通常位于/etc/emqx/emqx.conf，是集群部署时最常用的配置入口。 - 环境变量：以
EMQX_为前缀，例如EMQX_NODE__NAME、EMQX_LISTENERS__TCP__DEFAULT__BIND。容器化部署（Docker、K8s）几乎全靠它注入配置。 - 命令行参数：启动时通过
emqx start或emqx foreground附加的参数，优先级最高，常用于临时覆盖或调试。
覆盖规则是“高优先级覆盖低优先级”，且是按配置项逐项覆盖，不是整份文件替换。也就是说，环境变量只覆盖它声明的那一项，其余项仍以 emqx.conf 为准。理解这一点，才能解释为什么“只加了一个环境变量，其他配置没丢”。
二、环境变量的命名转换规则
环境变量不是随便起名，它遵循“配置路径 → 大写 + 双下划线”的转换规则。以配置项 listeners.tcp.default.bind 为例：
- 把点号
.替换为双下划线__； - 整体转为大写；
- 加上
EMQX_前缀。
于是得到 EMQX_LISTENERS__TCP__DEFAULT__BIND。注意是双下划线，单下划线会被当作名称的一部分，写错就不会生效。这条规则是排查“环境变量没起作用”的第一检查点。
三、核心配置项修改示例
下面给出一份可直接参考的 emqx.conf 片段，覆盖监听端口、节点名、认证与日志四类高频配置：
node {
name = "emqx@10.0.0.11"
cookie = "emqx_secret_cookie"
}
listeners.tcp.default {
bind = "0.0.0.0:1883"
max_connections = 102400
}
listeners.ssl.default {
bind = "0.0.0.0:8883"
ssl_options {
certfile = "/etc/emqx/certs/server.crt"
keyfile = "/etc/emqx/certs/server.key"
}
}
log.console.level = warning
log.file.level = info
修改后不要直接重启，先做配置校验：
emqx conf check
# 输出 ok 表示语法与取值合法
如果校验报错，EMQX 会指出具体路径，例如 listeners.ssl.default.ssl_options.certfile 文件不存在。先修文件路径，再谈重载。
四、热重载：哪些能热更，哪些必须重启
热重载的价值在于不中断现有连接。EMQX 支持通过 emqx ctl conf reload 重新加载配置文件，但并非所有配置项都能热生效。判断依据是：该配置是否影响进程启动参数或底层资源绑定。
| 配置类别 | 典型配置项 | 是否支持热重载 |
|---|---|---|
| 日志级别 | log.console.level | 支持，立即生效 |
| 认证与授权 | authentication、authorization | 支持，新连接按新规则 |
| 监听端口 | listeners.tcp.default.bind | 不支持，需重启 |
| 节点名与 Cookie | node.name、node.cookie | 不支持，需重启 |
| 限流与连接数 | max_connections | 部分支持，视版本而定 |
热重载的标准操作流程如下：
- 编辑
emqx.conf，只改动支持热更的项； - 执行
emqx conf check校验语法； - 执行
emqx ctl conf reload触发重载； - 用
emqx ctl conf show log.console.level确认新值已生效； - 观察日志与连接数，确认无异常断开。
五、优先级冲突的排查方法
当“改了配置却不生效”时，按以下顺序定位：
- 先用
emqx ctl conf show <配置路径>查看运行时实际值，而不是看文件； - 若运行时值与文件不一致，检查是否存在同名环境变量；
- 再检查启动命令是否带了覆盖参数；
- 确认修改的是当前节点实际加载的配置文件路径，而非备份文件。
掌握这三层来源与覆盖顺序后，配置修改就从“碰运气”变成“可推理”：先确定目标项属于哪一层，再判断它能否热更，最后用运行时查询验证结果。这套方法在单机、Docker 与 K8s 部署中同样适用。