语言包未加载的典型表现是lang('login')仍返回默认语言字符串且无报错，根源在于路径拼接错误、文件命名不规范（须为zh-cn.php等小写短横线格式）、目录位置错误（须为app/lang/或extend/vendor/lang/）、未清空缓存（Lang::setLocale()后需调用Lang::clear()）及配置项干扰（如lang_auto_detect=true可能覆盖手动设置）。
语言包文件没被正确加载的典型表现
切换语言后，lang('login') 依然返回中文（或默认语言）字符串，控制台无报错，Lang::getLangSet() 显示当前语言已变更——这说明语言切换逻辑走通了，但语言包内容根本没载入。
ThinkPHP 的多语言加载是「按需加载 + 缓存」机制：只有在首次调用 lang() 且对应语言包未加载时，才会尝试从预设路径读取 PHP 文件。常见断点在于路径拼接错误或文件命名不规范。
- 语言包文件必须是
zh-cn.php、en-us.php这类小写短横线格式，zh_CN.php或zhcn.php均不会被识别 -
lang/目录必须位于app/lang/（应用级）或extend/vendor/lang/（扩展级），不能放在public/lang/或随意子目录下 - 若使用模块化结构（如
app/index/lang/zh-cn.php），需确保当前请求路由命中该模块，否则模块级语言包不会触发加载
验证语言包实际加载路径与文件是否存在
ThinkPHP 不会主动报出「语言包文件不存在」的警告，而是静默跳过。最直接的调试方式是临时在 think\lang\Lang.php 的 load() 方法中加一行日志：
file_put_contents(RUNTIME_PATH . 'lang_debug.log', $file . PHP_EOL, FILE_APPEND);
然后切换语言并触发一次 lang() 调用，查看生成的 lang_debug.log 中记录的 $file 路径是否真实存在、是否可读。
立即学习“PHP免费学习笔记（深入）”；
- 典型错误路径：
/var/www/app/lang/zh-cn.php（正确） vs/var/www/app/lang/zh-cn/zh-cn.php（多了一层目录，TP 不会自动补） - 注意 Linux 系统区分大小写，
ZH-CN.PHP和zh-cn.php是两个文件 - 如果路径中出现
zh-cn.php但文件实际叫zh_cn.php，则加载失败且无提示
Lang::setLocale() 后 lang() 仍返回旧值的原因
语言切换不是实时生效的——Lang::setLocale('en-us') 只改变当前会话的语言标识，但已加载的语言包（比如之前加载过的 zh-cn.php）仍在内存中缓存，lang() 会优先从缓存读，不会重新加载新语言包。
- 必须在
Lang::setLocale()后手动清空语言包缓存：Lang::clear(); - 若使用了多级语言包（如
app/lang/zh-cn/common.php+app/lang/zh-cn/user.php），Lang::clear()会清空全部，无需单独处理 - 切忌在控制器构造函数里调用
Lang::setLocale()却忘了Lang::clear()，这是线上最常见的「切换无效」原因
配置项 lang_switch_on 和 lang_auto_detect 的干扰
这两个开关会影响语言初始化时机和来源，容易掩盖真实问题。
-
lang_switch_on = false（默认值）时，系统不会自动根据 URL 参数（如?lang=en-us）切换语言，只能靠代码手动调用Lang::setLocale() -
lang_auto_detect = true（默认值）会读取浏览器Accept-Language头，可能覆盖你手动设置的语言，建议开发期设为false排查 - 检查
config/lang.php中是否误将default_lang写成zh_CN（应为zh-cn），该配置只影响初始语言，但拼写错误会导致后续加载路径错误
路径拼错、缓存没清、配置名大小写混用——这三个点卡住 90% 的多语言问题。别急着查中间件或钩子，先确认 lang_debug.log 里写的路径能不能 file_exists() 返回 true。
