私有包必须在项目composer.json中显式声明repositories数组，否则Composer报“Could not find package”；需按vcs或composer类型配置URL，并禁用packagist.org，同时确保minimum-stability和prefer-stable统一设置以保障版本稳定性。
私有包必须走 repositories 声明，不能靠 Packagist 代理
Packagist 默认不索引私有仓库，即使你把内部 Git 地址设为 public，它也不会自动抓取或缓存。直接写 "your-vendor/core-utils": "^1.2" 而不声明 repositories，Composer 会报 Could not find package your-vendor/core-utils。
正确做法是在 composer.json 顶层加 repositories 数组：
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:your-org/core-utils.git"
}
],
"require": {
"your-vendor/core-utils": "^1.2"
}
}
- URL 必须是可被所有开发者访问的 Git 地址（推荐 SSH，避免 token 泄露）
- 多个部门共用多个私有包时，每个都得单独列在
repositories里，顺序无关 - 如果用 Satis 或 Private Packagist，
type改为composer，url指向其packages.json地址
minimum-stability 和 prefer-stable 必须统一配置
不同部门可能习惯用 dev-master 或 dev-main 测试新功能，但生产环境绝对不能允许这种不稳定版本进入。一旦某个部门的 composer.json 没设 minimum-stability，而核心包只打了 v1.2.0 tag，Composer 就可能拉下未 tag 的 dev 分支，导致行为不一致。
强制要求所有项目根目录的 composer.json 包含：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"minimum-stability": "stable",
"prefer-stable": true
}
-
minimum-stability是全局底线，prefer-stable让 Composer 在满足约束前提下优先选 stable 版本 - 即使核心包自己发布了
beta版，只要没显式写"your-vendor/core-utils": "@beta"，就不会装 - CI 流水线应校验该配置是否存在，缺失则失败
审查依赖来源：用 composer show --tree 定位私有包实际加载路径
跨部门协作中，常出现“明明用了新版 core-utils，但日志里还是旧逻辑”——大概率是某层间接依赖悄悄引入了另一个同名私有包，或通过 fork、镜像仓等非主源加载。
执行以下命令能暴露真实来源：
composer show --tree your-vendor/core-utils
- 输出会显示该包从哪个
repositoriesURL 解析而来，以及是否被其他包覆盖（如another-dep requires your-vendor/core-utils:1.0.0） - 若看到路径里含
https://satis.internal/或https://private-packagist.yourcorp.com/，说明走的是中心化仓库；若显示git@github.com:fork-org/core-utils.git，就得立刻排查是否绕过了审批流程 - 建议在每日构建脚本里加入该检查，并比对预期 URL
权限隔离靠仓库层，不是 Composer 层
Composer 本身不提供权限控制。所谓“财务部只能用 core-utils v1.2，研发部可用 v1.3”，不能靠 composer.json 配置实现，必须由底层 Git 仓库或私有 Packagist 控制。
- Satis 不支持权限，所有公开的
packages.json对所有人可见，适合全公司通用包 - Private Packagist On-Premise 支持 Team 级别同步策略：可配置 “Finance-Team 只同步
core-utils的release/v1.2分支”，研发团队则同步main - Git 层面可通过 branch protection + CI gate 实现：例如，只有
release/*分支的 push 才触发 Satis 构建，其他分支不入库
最易忽略的一点：即使你用 Private Packagist 做了权限分组，也要确保各部门的 composer.json 里 repositories 指向的是带身份认证的私有仓库地址（如 https://packagist.yourcorp.com/api/），而不是无认证的公开镜像站——否则权限形同虚设。
