核心问题是locale、时区、扩展行为与缓存路径未对齐，导致post-install-cmd静默失败、autoload_classmap.php生成异常、config:cache写入乱码，最终冷启耗时翻倍；必须在docker构建中固化en_us.utf-8 locale、asia/shanghai时区，于warmup.php中做编码守卫，并确保opcache_reset()在预热末尾执行。
中文环境下的 Composer 缓存预热，核心问题不在语言本身，而在于 locale、时区、扩展行为与缓存路径三者未对齐——导致 post-install-cmd 静默失败、autoload_classmap.php 生成异常、config:cache 写入乱码文件，最终集群节点冷启耗时翻倍。
为什么中文路径/内容会让 post-install-cmd 失败
不是 Composer 不支持中文，而是它调用的底层 PHP 函数（如 mb_detect_encoding()、json_encode()、file_put_contents()）在缺失正确 locale 时会退化行为：
-
mb_detect_encoding($str)返回false，导致 Laravel 配置解析中断，config:cache命令 exit(1) 但无日志 -
json_encode(['msg' => '你好'])返回null（未启用JSON_UNESCAPED_UNICODE且 locale 不支持 UTF-8） -
file_put_contents('bootstrap/cache/config.php', $content)在 C locale 下写入二进制乱码，后续require直接 parse error
这类失败不会打断 composer install 主流程，只报 “Script ... returned with error code 1”，而 CI 日志常被截断或忽略。
Docker 构建阶段必须固化 locale 和时区
不能依赖宿主机或 K8s node 的环境。必须在 Dockerfile 中显式设置，且顺序不能错：
- 基础镜像选
php:8.2-fpm-alpine后，立刻运行：RUN apk add --no-cache tzdata && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && echo "Asia/Shanghai" > /etc/timezone - 再安装 glibc 或 musl-locales（Alpine）：
RUN apk add --no-cache gcompat && echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen && /usr/bin/locale-gen - 最后设环境变量：
ENV LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8（别用zh_CN.UTF-8，部分 Alpine 版本不带该 locale）
验证方式：构建后进容器执行 locale，输出必须含 UTF-8 且无 warning；再跑 php -r "var_dump(json_encode(['测试']));" 应返回字符串而非 null。
缓存预热脚本必须做 locale 守卫
即使 Docker 层设置了 locale，PHP 脚本仍可能因 putenv() 被覆盖或未生效。在 scripts/WarmUp.php 开头加硬性检查：
if (setlocale(LC_ALL, 'en_US.UTF-8') === false) {
error_log('FATAL: en_US.UTF-8 locale not available');
exit(1);
}
if (mb_internal_encoding() !== 'UTF-8') {
mb_internal_encoding('UTF-8');
}
同时确保所有 artisan 命令显式指定编码：
- 改用
php -d default_charset=UTF-8 artisan config:cache而非裸php artisan config:cache - 在
bootstrap/app.php顶部加ini_set('default_charset', 'UTF-8');
否则 view:cache 编译中文 Blade 模板时，生成的 PHP 文件头部可能缺 declare(strict_types=1); 或含 BOM，引发语法错误。
vendor 层缓存 + 中文 locale 必须一起 baked in 镜像
只固化 locale 不够，只固化 vendor 也不行。二者必须在同一个构建阶段完成，且顺序严格：
-
COPY composer.json composer.lock ./→RUN composer install --no-dev --no-scripts --optimize-autoloader→RUN apk add ... && set locale→RUN php scripts/WarmUp.php→COPY . . - 关键点：
WarmUp.php必须在 locale 设置**之后**、COPY . .**之前** 执行，否则bootstrap/app.php读不到正确环境变量，APP_ENV判断失效 - 最终镜像里
bootstrap/cache/下的config.php、routes-v7.php等文件，修改时间必须早于构建时间戳（可用stat bootstrap/cache/config.php验证），否则 K8s initContainer 会误判为“需重生成”
最容易被忽略的是：中文环境下 opcache 对含中文路径的缓存文件注册不稳定，必须在 WarmUp 脚本末尾加 opcache_reset(); 并确保 PHP-FPM 启动前已加载 opcache 扩展——否则预热白做。
