ThinkPHP数据库配置文件前缀编码端口详细速查手册

ThinkPHP数据库配置看起来不过是几项基础参数，但偏偏是表前缀、字符集和端口这三个“老三样”，最常让开发者踩坑。很多人跑来问我：“我明明配了啊，怎么还报错？” 其实关键不是你配置了没有，而是你有没有配准——尤其在ThinkPHP 5.x、6.x、7.x之间来回切换时，字段名、配置位置、甚至默认值的处理方式都存在细微差异。只要一步没跟上，往往就得折腾半天才能排错。

表前缀 prefix：全局配置生效，但模型类默认不读取

先说表前缀。这个参数必须放在数据库连接配置的最顶层，千万别手滑塞进params数组里——TP6+早就废弃那种写法了。而且你得知道，它只对Db::name('user')这种查询方式生效；模型类默认根本不读取这个配置项，很多新手都在这上面栽跟头。

• 在.env文件里配置：DATABASE_PREFIX=tp_（全大写加下划线，不要加引号）
• 在config/database.php对应的连接项中配置：'prefix' => 'tp_'（小驼峰键名，字符串值）
• 如果使用模型，你需要手动处理：要么在模型里重写getTableName()方法，要么直接定义protected $table = 'tp_user';

字符集 charset：必须使用 utf8mb4，别无选择

接着看字符集。我见过太多人还在沿用utf8，觉得“够用了”。但MySQL的utf8实际上是个阉割版，最多只支持3字节字符——这意味着emoji和部分生僻汉字直接存不进去，要么乱码，要么报错。正确的做法是，把utf8mb4写死在配置里不动。

• .env就写：DATABASE_CHARSET=utf8mb4
• database.php里对应配置：'charset' => 'utf8mb4'
• 别忘了同步检查MySQL服务端以及数据库/表的collation，建议选用utf8mb4_unicode_ci这类排序规则

端口 hostport：默认值不意味着“可以不写”

最后说端口。很多人觉得默认就是3306，干脆不配置。但现实情况是——Docker环境、云数据库、本地多个MySQL实例跑在不同端口上，这些场景都很常见。你漏写了端口，报错信息往往含糊不清，排查半天都可能定位不到根因。所以就算你用默认值，也建议明确写出来。

• .env里：DATABASE_PORT=3306（注意键名是DATABASE_PORT，不是DB_PORT）
• database.php里：'hostport' => '3306'（TP6+统一使用hostport，不是port也不是DB_PORT）
• TP5.x还认port，但到了TP6/7，必须用hostport，否则配置会被直接忽略

这三项都不算复杂，但正因为简单，才容易被忽视。把这些细节抠准了，后续开发能省下大把排查时间。