ThinkPHP多语言分组是模块化项目中语言包加载顺序和覆盖逻辑的底层机制，按模块/lang/语言码/分组名.php→模块/lang/语言码/common.php→应用/lang/语言码/分组名.php→应用/lang/语言码/common.php优先级加载，分组名必须小写且需定义GROUP_NAME常量才触发，lang()仅查已加载包，未正确加载会导致空值或错值。
ThinkPHP 的多语言分组不是“可选功能”，而是模块化项目中语言包加载顺序和覆盖逻辑的底层机制——不理解它，lang() 就会返回空或错值，且几乎不报错。
lang/ 目录下怎么组织分组语言包
分组语言包本质是路径层级叠加：ThinkPHP 会按固定优先级依次尝试加载多个 common.php（或指定分组名的 PHP 文件），从高到低为：模块/lang/语言码/分组名.php → 模块/lang/语言码/common.php → 应用根目录/lang/语言码/分组名.php → 应用根目录/lang/语言码/common.php。
比如你有 app/module/user/ 模块，又启用了分组（GROUP_NAME = 'user'），那么系统会先找：lang/zh-cn/user/lang.php；找不到再找：lang/zh-cn/user.php；再找不到才 fallback 到 lang/zh-cn/common.php。
关键点：
立即学习“PHP免费学习笔记（深入）”；
-
分组名.php和common.php是并列关系，不是包含关系；两者可以共存，但内容不自动合并 - 分组文件名必须全小写，
User.php或USER.PHP都不会被识别 - 分组语言包只在定义了
GROUP_NAME常量时才触发加载，普通模块（未显式设 GROUP_NAME）不会走这层逻辑 - 如果用了路由分组（如
Route::group('admin', ...)），它和语言分组无关，别混淆
lang() 函数查不到分组键值的常见原因
lang('user_login_failed') 返回空字符串，大概率不是键不存在，而是没加载对文件。ThinkPHP 的 lang() 只查当前已加载的语言包数组，不递归扫描所有可能路径。
典型漏加载场景：
- 控制器里调用
lang()前，没触发对应分组语言包的自动加载（比如忘了在中间件里注册LoadLangPack） - 分组语言包路径正确，但文件里没
return [...]，或者末尾多了 BOM 头或空格，导致 PHP include 失败，静默跳过 - 配置中没开
'allow_group' => true（部分老版本需手动开启，新版默认支持但文档未强调） - 你在
app/middleware.php中把LoadLangPack放在了 session 或 auth 中间件之后——而语言检测依赖 cookie/session，顺序错了就拿不到用户偏好
如何手动强制加载某个分组语言包
当自动加载链路不可控（比如 AJAX 接口、命令行任务、或异步队列中），推荐显式加载：
在需要的地方直接调用：
Lang::load(LANG_PATH . 'zh-cn/user.php');
注意：LANG_PATH 是常量，指向 app/lang/；路径拼接必须严格，不能漏斜杠或写成 LANG_PATH . '/zh-cn/user.php'（Windows 下可能出错）。
更安全的做法是封装一个辅助函数：
function load_lang_group($group, $lang = null) {
$lang = $lang ?: app()->lang->getLangSet();
$file = LANG_PATH . $lang . '/' . strtolower($group) . '.php';
if (is_file($file)) {
Lang::load($file);
}
}然后在控制器里：load_lang_group('user');
这个方式绕过了自动探测逻辑，适合精准控制，但要注意重复加载无副作用（Lang::load() 内部会去重）。
分组语言包和缓存、部署的坑
线上环境最容易翻车的是缓存和大小写问题：
- 语言包文件修改后，
lang()还是旧内容？检查是否开了lang_cache_on配置，或清空runtime/lang/缓存目录 - Linux 服务器上，
lang/ZH-CN/common.php和lang/zh-cn/common.php是两个不同路径；开发时用 Windows 不报错，上线就失效 - Git 默认不区分大小写，
zh-CN提交后可能被转成zh-cn，建议在项目根目录加.gitattributes：* text=auto eol=lf
*.php text diff=php
lang/** export-ignore - 使用 SaaS 部署（如阿里云函数计算）时，
LANG_PATH可能被重定向，需确认运行时实际路径是否可读
最隐蔽的问题：分组语言包里的键名和 lang() 调用时不一致，比如包里写 'login_fail' => '登录失败'，代码里却写 lang('user_login_fail')——这种错误没有任何提示，只能靠人工核对或加日志断言。
