repositories字段必须是根级JSON数组，含type和合法url；写错格式、漏配置或认证失效均导致require报“Could not find package”。
composer.json 里 repositories 没写对，require 就一定失败
Composer 默认只查 packagist.org，不扫描本地目录、不猜测 Git 地址、不继承全局配置。你漏掉 repositories 字段，或者写成对象而非数组，composer require vendor/name 就会直接报 Could not find package。
必须满足三点：
-
repositories是 JSON 数组，每个项含"type": "vcs"（Git/SVN/Hg）或"type": "composer"（Satis 等服务） -
url指向 Git 仓库根目录（即包含该私有包composer.json的那个地址），不要带.git后缀 - 如果混用多个源，顺序决定优先级：Composer 从上到下匹配，第一个命中就停，后面同名包被忽略
错误示例："repositories": {"my-vcs": { "type": "vcs", "url": "..." }} —— 这是对象，不是数组，Composer 直接忽略。
auth.json 权限不对或放错位置，认证就静默失效
HTTPS 私有库（如 GitLab 内网实例）需要凭据，但凭据绝不能拼在 URL 里，也不能写进 composer.json。唯一合法路径是 auth.json，且它必须满足两个硬性条件：
- 位置：项目根目录（与
composer.json同级）优先；其次才是COMPOSER_HOME或默认~/.composer/auth.json - 权限：Linux/macOS 下必须是
600（chmod 600 auth.json），否则 Composer 会跳过读取，不报错也不提示
内容结构要严格：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"http-basic": {
"gitlab.example.com": {
"username": "deploy",
"password": "xxx"
}
},
"github-oauth": {
"github.com": "token_xxx"
}
}
注意：http-basic 的 key 是域名（如 gitlab.example.com），不是完整 URL；github-oauth 的 token 至少要有 read:packages 权限。
私有包的 version 不是 composer.json 里写的，而是 Git tag
Composer 解析 VCS 类型仓库时，完全忽略私有包自身 composer.json 中的 version 字段。它只认 Git 的 tag 和分支名。
- 想用
"^1.0"，就必须打合规语义化 tag：v1.0.0或1.0.0（v1.0或1.0不识别） - 没打任何 tag？那只有
dev-main、dev-master这类虚拟版本可用，require 时得写"dev-main"，且项目根composer.json得配"minimum-stability": "dev"和"prefer-stable": false - 改了 tag 对应的 commit 并强制推送后，Git 服务器缓存可能未刷新，Composer 仍拉旧版 —— 此时需清缓存：
composer clear-cache
调试命令：composer show vendor/name --all 能列出 Composer 实际识别出的所有版本，比猜靠谱得多。
Satis 构建后 packages.json 为空，大概率是没 rebuild 或权限问题
Satis 不是实时同步服务。它只在你手动运行 php bin/satis build satis.json web/ 时，才去克隆 Git 仓库、读 composer.json、生成静态 packages.json。刚 push 新 tag 却找不到包？八成是忘了 rebuild。
- 确认
satis.json中repositories列表已包含该私有 Git 地址，且协议可用（如用 HTTPS，别写成git@） - 确保 Satis 构建机有权限访问目标仓库（SSH key 或 PAT 已配置）
- 构建命令必须在
satis.json所在目录执行，web/是输出目录，别写错路径 -
output-dir必须有写权限，磁盘空间够（大量临时克隆很吃空间）
检查最简单方式：用浏览器打开 https://your-satis-domain.com/packages.json，搜索包名，看是否存在。不存在，就不是客户端问题，是 Satis 根本没索引进去。
