作为常年跟TiDB集群打交道的运维，碰到TiKV/PD修改toml后不生效的情况太常见了，给你梳理几个最容易踩的坑，按顺序排查基本能解决：

1. 没搞清楚静态配置和动态配置的区别 #

TiKV/PD的配置分两类：

• 静态配置：是服务启动时加载的核心配置，比如TiKV的storage.data-dir、PD的data-dir，这类配置修改后必须重启服务才会生效，光改toml文件没用。
• 动态配置：比如PD的schedule.max-replicas、TiKV的raftstore.raft-log-gc-threshold，这类可以在线重载，但你改了本地toml后，必须执行重载操作让服务读取新配置，不然服务还是用内存里的旧配置。

怎么区分？可以看对应版本的官方文档标注，或者用pd-ctl config show（PD）、tiup ctl tikv config show（TiKV）查看当前生效的动态配置项。

2. 修改了错误的配置文件 #

很多新手会找错配置文件路径！比如用TiUP部署的集群，每个节点的配置文件在/tidb-deploy/{component}-{port}/conf/目录下（比如PD是pd-2379/conf/pd.toml），而不是你下载的模板文件或者随便存的副本。

确认方法：执行ps aux | grep pd-server或者ps aux | grep tikv-server，看进程启动参数里的--config指定的路径，改那个文件才有用。

3. 改完文件没执行重载/重启操作 #

• 对于动态配置：改完toml后，要么用集群管理工具重载，比如tiup cluster reload your-cluster-name --component pd（或tikv）；要么给进程发SIGHUP信号：kill -HUP <pid>，这样服务会重新加载配置文件里的动态项。
• 对于静态配置：只能重启服务，比如tiup cluster restart your-cluster-name --component tikv。

如果只改文件不做这些操作，服务永远不会主动读取新配置。

4. TOML格式写错了 #

TOML对格式要求很严格，一点点错误都会导致配置加载失败：

• 键值对等号前后要有空格：比如storage.block-cache.capacity = "10GB"才对，写成storage.block-cache.capacity="10GB"可能会被忽略。
• 表格（比如[raftstore]）要用方括号，不能用其他符号。
• 特殊字符的字符串要加引号，比如路径里有空格的话。
• 注释必须用#开头，不能用//。

可以用官方工具检查语法：比如TiKV的tiup ctl:v<your-version> tikv config check --config /path/to/tikv.toml，PD同理，有错误会直接提示。

5. 配置项跟集群版本不兼容 #

有些配置项是特定版本后才新增的，或者生效方式变了。比如TiKV的storage.block-cache.capacity在v5.0之前只能静态配置，v5.0之后才支持动态重载；PD的某些调度配置在旧版本里根本不存在。

如果你的集群版本比较老，改了高版本才有的配置，自然不会生效。一定要对照你当前集群版本的官方文档来修改配置。

6. 手动改的配置被集群管理工具覆盖了 #

如果用TiUP或TiDB Operator管理集群，手动修改节点上的toml文件是不靠谱的——下次执行tiup cluster reload或者Operator同步配置时，会被集群的配置模板覆盖。

正确做法：

• TiUP集群：用tiup cluster edit-config your-cluster-name修改全局配置模板，然后执行重载，所有节点会自动同步正确的配置。
• TiDB Operator：修改CR（Custom Resource）里的配置字段，Operator会自动把配置同步到Pod中。

7. 没正确验证配置是否生效 #

有时候不是没生效，是你验证方式错了！不要只看本地的toml文件，要去查服务实际加载的配置：

• PD：用pd-ctl config show（或者TiDB Dashboard的配置页面）看当前生效的配置。
• TiKV：用tiup ctl:v<your-version> tikv config show --host tikv-ip:20160查看节点的生效配置。

另外，有些动态配置（比如PD调度）生效需要一点时间，别急着下结论，等几分钟再验证。

内容的提问来源于stack exchange，提问作者Caitin Chen