如何配置并使用ThinkPHP多语言中间件？

本文共计801个文字，预计阅读时间需要4分钟。

在Lang中，若未注册中间件，则等同于未开启——语言包根本不会加载。例如，`Lang::get()` 返回空或默认值，不会报错，且不消耗特殊时间。

Lang中间件必须显式注册才能生效

ThinkPHP 默认不启用 Lang 中间件，哪怕你配了 lang_switch_on => true 也没用。它不像路由或日志中间件那样自动挂载。

• 打开 app/middleware.php，确认 think\middleware\Lang 在数组中（不是被注释掉）
• 多应用模式下，每个应用目录（如 app/admin/middleware.php）都得单独加一遍
• 中间件顺序很重要：必须在 SessionInit 之后、路由调度之前执行；否则读不到 $_COOKIE['think_lang']，Lang::detect() 拿不到上下文

Cookie 键名和路径必须严格匹配

Lang 中间件只认 think_lang 这个 Cookie 名，不是 lang、language 或其他自定义名。设错就完全跳过切换逻辑。

• 写 Cookie 时必须用 cookie('think_lang', 'ja-jp')，别手写 setcookie()
• 前端 JS 写 Cookie 也得确保键名是 think_lang，且 path 和 domain 与后端一致（通常为 / 和当前域名）
• Lang 中间件只在请求初始化阶段读一次 Cookie，后续改 $_COOKIE 数组无效

语言包路径和文件结构不能有偏差

ThinkPHP 按固定路径加载语言包：lang/{lang}/，不是按文件名、也不是按配置别名。任何大小写、路径层级或文件缺失都会静默失败。

立即学习“PHP免费学习笔记（深入）”；

• 目录必须全小写：lang/zh-cn/ ✔️，lang/ZH-CN/ ❌
• 语言包文件需放在对应子目录下，例如 lang/zh-cn/common.php，不能是 lang/zh_cn/common.php 或 lang/zh-cn.php
• Lang::set('ja-jp') 会立刻生效，但不写 Cookie；要持久化，得自己调 cookie('think_lang', 'ja-jp')
• 如果 lang/ja-jp/common.php 缺失，Lang::get('submit') 就回退到默认语言，不提示、不报错

第三方扩展语言包需要手动加载

vendor 下的扩展语言包不会被 Lang 中间件自动扫描，ThinkPHP 只加载 lang/ 目录下的应用级语言包。

• 在 app/common.php 或启动类中间件中调用 Lang::load() 手动加载
• 路径必须是绝对路径，例如：Lang::load(VENDOR_PATH . 'topthink/think-captcha/lang/zh-cn.php')
• 注意：Lang::load() 必须在 Lang 类初始化之后调用，太早（比如 config 加载阶段）会无效

最常被忽略的是中间件注册和 Cookie 键名——这两点一错，整个多语言流程就卡死在第一步，后面所有配置和语言包都白搭。