Composer报“Could not find package”是因为未在composer.json的repositories顶层声明Gitee私有库vcs源，且auth.json位置、格式、权限及包名匹配等细节必须严格符合要求。
Composer报“Could not find package”是因为没声明vcs仓库
直接composer require your-org/your-package在Gitee私有库上必然失败——Composer根本不会去Gitee查包，它只默认访问Packagist。必须手动在项目composer.json的repositories顶层字段里加一条vcs源声明。
常见错误包括：
- 把
https://gitee.com/your-org/your-package（网页地址）当克隆地址填进去 - 漏掉
"type": "vcs"，写成"type": "package"或干脆不写type - 把
repositories塞进config或extra里，而不是和require平级的顶层字段
正确写法示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitee.com/your-org/your-package.git"
}
],
"require": {
"your-org/your-package": "dev-main"
}
}
Gitee HTTPS拉取卡住或401，auth.json位置和格式必须精准
Gitee私有库走HTTPS协议时，Composer底层调用git clone，但不会弹出交互式密码框，也不会读系统凭据管理器——它只认auth.json，且只在两个位置找：项目根目录的./auth.json，或全局的~/.composer/auth.json（注意不是~/.config/composer/auth.json，后者是旧版路径，新版已弃用）。
auth.json内容必须是标准JSON对象，http-basic是顶层字段，不能嵌套：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"http-basic": {
"gitee.com": {
"username": "your-gitee-username",
"password": "your-personal-access-token"
}
}
}
- Token需在Gitee个人设置 → 私人令牌中生成，权限勾选
projects（等价于read_repository） - 用户名填Gitee账号名，不是邮箱；密码字段填Token，不是登录密码
- 文件权限必须设为
600：chmod 600 auth.json，否则Composer会静默忽略
require里的包名必须和私有库composer.json的name字段逐字匹配
Composer不看Git URL路径，只比对require中的字符串和私有库根目录下composer.json里的"name"字段。大小写、中划线、斜杠前后顺序，差一个字符就报Could not find package。
假设你的Gitee仓库地址是https://gitee.com/my-company/internal-utils，但里面composer.json写的是：
{ "name": "MyCompany/internal-utils", ... }
那么require里必须写"MyCompany/internal-utils"，写成"mycompany/internal-utils"或"my-company/internal-utils"都会失败。
- 检查方式：进私有库目录，执行
grep -o '"name": *"[^"]*"' composer.json - 别依赖Gitee页面显示的“组织/项目名”，它和
name字段无关 - 如果私有库还没提交
composer.json，或者name为空，Composer直接拒绝识别，不报具体错
版本写dev-main能装，但上线前必须切到tag
"your-org/pkg": "dev-main"可以临时装，但这是危险操作：每次composer update都可能拉到新提交，破坏部署一致性。生产环境必须用Git tag驱动语义化版本。
- 在私有库打tag：
git tag v1.2.0 && git push origin v1.2.0 -
require改写为"your-org/pkg": "^1.2"或"1.2.0"，Composer会自动匹配v1.2.0标签 - Tag名必须带
v前缀（如v1.2.0），Gitee不支持1.2.0裸数字tag（与GitHub不同） - 分支别名（如
"dev-main as 1.2.x-dev"）仅适合开发联调，CI/CD流程中应禁用minimum-stability: dev，避免意外装入-dev包
最易被忽略的一点：Gitee私有库的.git后缀在url里建议保留，虽然部分场景能fallback，但在CI环境（尤其是Docker构建）中，省略.git常导致git ls-remote探测失败，最终卡在“Updating dependencies”。
