在使用 Composer 管理 php 项目依赖时，如果需要引入私有包（比如公司内部组件），直接从公开 Packagist 安装显然不可行。这时就需要配置私有仓库，无论是基于 Packagist 私有实例还是自建 Satis 静态服务器。关键在于如何让整个流程既安全又简洁，不暴露凭据、便于团队协作。

配置私有仓库源

Composer 支持多种仓库类型，最常见的是 composer（Packagist 兼容）和 package 类型。对于私有 Packagist 或 Satis，通常使用 composer 类型：

在项目 composer.json 中添加仓库配置：

{     "repositories": [         {             "type": "composer",             "url": "https://packages.example.com"         }     ] } 

这样 Composer 在解析依赖时会自动查询该源。Satis 构建的仓库也适用此方式，只需指向其 packages.json 所在地址即可。

安全地管理认证信息

访问私有仓库通常需要身份验证。避免将账号密码硬编码在 composer.json 中，应通过 Composer 的全局配置文件处理。

使用 HTTP 基本认证：

• 运行命令自动写入凭据：

composer config http-basic.packages.example.com username token-or-password 

执行后，Composer 会在用户主目录下的 auth.json（通常是 ~/.config/composer/auth.json）中保存凭证，不会提交到版本控制。

推荐做法： 将 auth.json 加入 .gitignore，团队成员各自配置本地认证。

优化镜像与回退策略

为提升安装速度并保证稳定性，可设置私有仓库为镜像或启用回退机制。

作为镜像（仅用于特定包）：

若私有仓库只托管部分包，其余仍从 packagist.org 获取，确保配置正确顺序：

有道小P

有道小P，新一代AI全科学习助手，在学习中遇到任何问题都可以问我。

64

查看详情

{     "repositories": [         {             "type": "composer",             "url": "https://packages.example.com"         },         {             "type": "composer",             "url": "https://packagist.org"         }     ] } 

Composer 会按顺序查找，先查私有源，再查公共源。

使用 Satis 的“聚合”特性：

Satis 可以合并多个上游源，在生成的 packages.json 中包含私有 + 公共包，此时可设为唯一源，并关闭默认 packagist：

{     "repositories": [         {             "type": "composer",             "url": "https://packages.example.com"         }     ],     "config": {         "secure-http": true,         "disable-tls": false     },     "packagist.org": false } 

此举能统一依赖来源，加快安装速度，适合内网环境。

自动化部署与令牌管理

CI/CD 环境中需自动拉取私有包，建议使用个人访问令牌（PAT）而非明文密码。

gitHub / gitlab 场景示例：

• 生成一个具有读取包权限的 PAT
• 在 CI 脚本中动态写入认证：

composer config http-basic.packages.example.com gitlab-ci-token $CI_JOB_TOKEN 

很多平台（如 GitLab CI）支持变量注入，配合脚本实现无感认证。

注意： 若私有仓库基于 VCS（如 Git），也可通过 ssh 密钥方式拉取，但需确保运行环境已配置好 SSH agent 和正确的 known_hosts。

基本上就这些。关键是把仓库配置清晰化，凭据隔离管理，结合 Satis 或私有 Packagist 实现可控分发。只要结构合理，私有包也能像公共包一样流畅使用。