根本原因是Windows编辑器（如记事本）默认保存UTF-8 BOM头，Linux下json_decode()拒绝解析带BOM的JSON，报syntax error却不明示BOM问题；其他诱因包括全角符号、单引号、末尾逗号等。
为什么 Windows 编辑的 composer.json 在 Linux 上会 validate 失败
根本原因不是换行符或大小写，而是 Windows 编辑器（尤其是记事本、VS Code 默认保存设置）容易往 composer.json 写入 UTF-8 BOM 头。Linux 下的 json_decode()（Composer 底层依赖）拒绝解析带 BOM 的 JSON，直接报 JSON parse error: syntax error, expecting '{' 或定位到第 1 行第 1 列——但错误信息不提 BOM，容易误判为文件损坏。
其他常见诱因：
- 从网页复制配置时混入全角空格、中文冒号（
：）、零宽字符（U+200B） - 用单引号包裹字段名或字符串值（
'name': 'foo'❌，必须双引号"name": "foo"） - 末尾多逗号（
"require": {"php": ">=8.1",}），Windows 编辑器常默认保留，而部分旧版 Composer 容忍，新版（2.5+）严格拒绝
如何在 Windows 上提前发现并修复这些问题
别等 push 到 CI 才暴露。本地执行三步验证即可覆盖 95% 的跨平台问题：
- 用 VS Code 或 Notepad++ 打开
composer.json，右下角确认编码是 UTF-8 without BOM（不是 “UTF-8” 单独一项） - 运行：
php -r "$j=file_get_contents('composer.json');$d=json_decode($j);if(!$d)echo json_last_error_msg()."\n";"—— 这比composer validate报错更早、更直白，且不依赖 Composer 版本 - 再跑：
composer validate --strict --no-check-publish。加--strict是关键：它强制校验字段值合法性（如"name"含空格、"version"写成"v1.0"），这些在非严格模式下静默通过，却会导致 Linux 上composer install失败
CI/CD 中必须加的防护参数组合
GitHub Actions 或 GitLab CI 里只写 composer validate 等于没校验。Linux runner 上默认用最新 Composer（2.9.6+），对 schema 更敏感，必须显式约束行为：
-
--strict：把拼错字段（如"autoloader"）、非法值（如"type": "libary"）转为硬性失败，而非警告 -
--no-check-publish：跳过 Packagist 发布检查（如description缺失），避免网络超时或非发布项目被拦 -
--no-check-lock：如果 CI 不生成 lock 文件（例如只做语法检查），加此参数防误报 - 不要加
--no-check-all：它会跳过 autoload、scripts 等核心块的结构校验，而这几块正是 Windows 开发者最易手误的地方
推荐 CI 步骤：composer validate --strict --no-check-publish --no-check-lock
容易被忽略的“合法但危险”写法
有些配置 composer validate 通过，但在 Linux 环境下运行时仍会出问题，因为它们触发了平台差异逻辑：
-
"autoload": {"psr-4": {"App\": "app/"}}：Windows 路径分隔符反斜杠在 JSON 字符串里需双写为\，否则 PHP 解析时被当转义符处理，导致自动加载失效 -
"config": {"fxp-asset": {"enabled": false}}：该插件已废弃，新版 Composer 直接忽略，但若旧版 CI 缓存残留，可能引发不可预测行为 -
"repositories": [{"type": "path", "url": "./packages/mylib"}]：Windows 路径.packagesmylib在 Linux 上不存在，validate 不查路径真实性，只认字符串格式
真正跨平台安全的做法是：所有路径用正斜杠（"./packages/mylib"），所有命名空间结尾加反斜杠（"App\"），所有版本约束不带空格（"php": ">=8.1" 而非 "php": ">= 8.1"）。
