composer.json 文件编码必须是 UTF-8 无 BOM,否则 Composer 会静默失败或报“找不到文件”“JSON decode error”;需用 file -i 或 VS Code 状态栏验证编码,Windows 记事本默认带 BOM,应换用 VS Code 等编辑器保存为纯 UTF-8。

composer.json 文件编码必须是 UTF-8 无 BOM
Composer 解析 composer.json 时对编码极其敏感。若文件保存为 UTF-8 with BOM 或 US-ASCII,它会静默失败或报“找不到文件”“JSON decode error”等不明确错误。
验证方式:file -i composer.json(Linux/macOS)或用 VS Code 底部状态栏查看编码。输出中若含 charset=utf-8-with-bom 或 us-ascii,就必须重存为纯 UTF-8(无 BOM)。
- Windows 记事本默认保存为 BOM 编码,务必换用 VS Code、Notepad++ 或 Sublime Text
- CI/CD 流水线中若用
echo '{...}' > composer.json生成文件,某些 shell 会加 BOM,建议改用printf '%s' '{...}' > composer.json - Git 提交后在另一台机器上拉取,可能因编辑器自动转码引入 BOM,需统一团队编辑器设置
终端环境变量 LANG 和 LC_ALL 必须设为 UTF-8
尤其在 Windows WSL、macOS 终端或 Linux SSH 会话中,若 $LANG 输出为 C 或为空,中文路径、错误提示、交互式输入都会乱码,甚至导致 auth.json 认证失败。
检查命令:echo $LANG 和 echo $LC_ALL。理想值应类似 en_US.UTF-8 或 zh_CN.UTF-8。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 临时修复:
export LANG=en_US.UTF-8 && export LC_ALL=UTF-8 - 永久生效:追加到
~/.bashrc或~/.zshrc,然后新开终端(source不足以让子进程继承) - Windows PowerShell 中需设系统级区域设置,而非仅改终端变量;WSL 用户建议在
/etc/wsl.conf中配[locale] LANG="en_US.UTF-8"
auth.json 的编码和权限必须同时正确
~/.composer/auth.json 是 Composer 读取私有仓库凭证的关键文件。它不仅要 UTF-8 无 BOM,还必须有可读权限(Linux/macOS 至少 -rw-------),否则认证跳过且不报错。
常见现象:执行 composer install 时反复提示“Authentication required”,但你确信账号密码正确——大概率是 auth.json 编码或权限问题。
- 验证编码:
file -i ~/.composer/auth.json,非charset=utf-8就重存 - 验证权限:
ls -l ~/.composer/auth.json,若显示?????或权限宽松(如-rw-rw-rw-),运行chmod 600 ~/.composer/auth.json - Windows 下注意路径是否被重定向到 OneDrive 或同步盘,某些云盘会干扰文件属性读取
COMPOSER_HOME 路径里不能含中文或 shell 变量
COMPOSER_HOME 是 Composer 查找全局配置、auth.json 和 vendor/bin 的根目录。一旦路径含中文字符(如 C:\用户\name\.composer)或用了 ~、$HOME,Composer 会直接忽略该变量,退回到默认路径(%APPDATA%\Composer 或 $HOME/.composer),导致你设的认证、镜像、脚本全部失效。
- Windows 正确写法:
setx COMPOSER_HOME "C:\Users\YourName\AppData\Roaming\Composer"(绝对路径,英文目录) - macOS/Linux 正确写法:
export COMPOSER_HOME="/Users/yourname/.my-composer"(不能写~/my-composer) - 设完必须新开终端验证:
composer config --list --global看 “Global configuration file” 是否指向你设的路径
真正卡住人的从来不是“有没有设”,而是“设了但 Composer 根本没读到”——它不报错,只沉默地走默认路径。每次怀疑编码或环境问题,先做三件事:file -i 看编码,echo $LANG 看终端环境,composer config --list --global 看实际加载路径。










