repositories 字段必须是数组而非对象，如["{"type":"composer","url":"https://packagist.org/"}"]；声明后官方源不再自动继承，需显式添加；私有 Git 仓库设 type="git"，自建 Composer 仓库用 type="composer"；禁用 packagist.org 后须手动添加镜像，且顺序影响查找优先级。
repositories 字段必须是数组，不是对象
很多人直接写成 {"repositories": {"packagist.org": {"type": "composer", "url": "https://packagist.org/"}}}，结果 Composer 报错：Invalid repository type, expected array。因为 repositories 的值必须是数组，哪怕只配一个仓库也要用方括号包起来。
- ✅ 正确写法：
"repositories": [{"type": "composer", "url": "https://packagist.org/"}] - ❌ 错误写法：
"repositories": {"packagist.org": {...}}或"repositories": {...} - 默认行为：不写
repositories时，Composer 自动包含官方 Packagist（packagist.org）；一旦声明该字段，官方源就**不会自动继承**，必须显式加回去
私有 Git 仓库要设 type=git，且 url 必须可被 git clone
想从 GitHub 私有库或公司内网 GitLab 拉包？不能只填 HTTPS 地址就完事。Composer 会尝试执行 git clone，所以 url 要匹配你本地 git 的访问能力。
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
- 如果你用 SSH 克隆私有库（如
git@github.com:user/repo.git），url就得写这个格式，且确保 ssh-agent 已登录、key 已加载 - 如果用 HTTPS + token（比如
https://<token>@github.com/user/repo.git</token>），token 必须有read:packages权限（GitHub）或对应仓库的读权限（GitLab） -
type必须是"git"，不是"vcs"（虽然它也能识别，但"git"更明确、兼容性更好） - 示例：
{"type": "git", "url": "https://gitlab.example.com/mygroup/mypackage.git"}
自建 Composer 仓库要用 type=composer，别漏掉 packages.json
搭了 Satis 或 Private Packagist？这类服务对外暴露的是一个含 packages.json 的静态目录，不是 Git 仓库。此时 type 必须为 "composer"，否则 Composer 会当成 VCS 处理，报 Could not fetch packages.json。
- 确认你的仓库根路径能直接访问到
https://your-repo.com/packages.json -
url填域名+路径即可，不用带/packages.json—— Composer 会自动拼 - 示例：
{"type": "composer", "url": "https://repo.mycompany.com/"} - 注意：Satis 生成的
packages.json默认不包含 dev 分支，若需安装dev-main，得在satis.json里配"require-all": true或显式列"require-dependencies": true
packagist.org 被禁用后必须手动加回，且位置影响优先级
有些团队为了安全或镜像策略，在 repositories 里写了 {"packagist": false}。这会彻底关掉官方源 —— 但很多人忘了补回国内镜像（如阿里云、腾讯云），导致所有非私有包都装不上。
-
{"packagist": false}是合法写法，作用是屏蔽默认源；但它本身不提供任何包，只是“关开关” - 想用阿里云镜像？得额外加一条：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 顺序很重要：Composer 按数组顺序查找包，前面的仓库匹配到了就不会往后找。把私有源放前面，公共镜像放后面
- 别依赖
composer config repo.packagist命令临时设置 —— 它只改全局或当前项目的config，不改repositories，对私有包发现逻辑无效
composer show -p 可验证仓库是否被识别；遇到包找不到，先跑 composer clear-cache 再试 —— 缓存里可能存着旧的 packages.json 索引。私有仓库的认证、HTTPS 证书、DNS 解析这些底层链路，比 composer.json 语法更容易卡住。 
