composer install 时指定本地压缩包需在 repositories 中声明 package 类型仓库，设置 dist.url 为 file:/// 绝对路径、dist.type 为 zip/tar，并确保压缩包根目录含合规 composer.json；artifact 类型则需配置目录路径并遵循 {vendor}/{package}-{version}.{ext} 命名规则。
composer install 时如何指定本地压缩包作为依赖源
Composer 默认从 packagist.org 或私有仓库拉取包，但某些场景（如离线环境、内部组件分发）需要直接用本地 .zip 或 .tar.gz 安装。关键不是“替换仓库”，而是让 Composer 把本地文件当成一个“包源”来解析和安装。
最直接有效的方式是：在 composer.json 的 repositories 中添加 package 类型仓库，并手动声明该包的元信息（name、version、dist），其中 dist.url 指向本地绝对路径或 file:// 协议地址。
-
dist.url必须是可访问的本地路径，推荐使用file:///absolute/path/to/pkg.zip格式（注意三个斜杠） -
dist.type必须明确设为zip或tar，不能省略 -
name和version必须与压缩包内composer.json中的一致，否则会校验失败 - 压缩包根目录必须包含有效的
composer.json，且不能有多余父级目录（即解压后应直接看到composer.json，而非pkg-1.0.0/composer.json）
为什么 artifact 配置不生效？常见路径陷阱
很多人误以为在 config.artifact 下配置路径就能自动扫描本地包——这是对 Composer artifact 仓库类型的误解。artifact 是一种**仓库类型**，它本身不“安装包”，而是让 Composer **扫描指定目录下所有符合命名规则的压缩包**（如 vendor-name/package-name-1.2.3.zip），并将其作为可用版本提供给 require。
所以真正起作用的是：repositories 中 type=artifact 的条目，而非 config.artifact（后者根本不存在）。
- 正确写法是：
"type": "artifact", "url": "/path/to/my/artifacts" - 路径必须是**目录**，不是单个 zip 文件
- 目录内压缩包文件名必须严格匹配
{vendor}/{package}-{version}.{ext}，例如：acme/utils-2.1.0.zip - 如果路径含空格或中文，务必 URL 编码或改用英文路径，否则 Composer 会静默跳过
- 执行
composer update后，可用版本才会被索引；install不会重新扫描 artifact 目录
实操：用本地 zip 安装一个无网络依赖
假设你有一个本地包 /tmp/mylib-1.0.0.zip，其内部结构为：
{
"name": "myorg/mylib",
"version": "1.0.0",
"autoload": { "psr-4": { "MyOrg\": "src/" } }
}
在项目根目录的 composer.json 中添加：
{
"repositories": [
{
"type": "package",
"package": {
"name": "myorg/mylib",
"version": "1.0.0",
"dist": {
"url": "file:///tmp/mylib-1.0.0.zip",
"type": "zip"
}
}
}
],
"require": {
"myorg/mylib": "1.0.0"
}
}
然后运行：
composer update myorg/mylib
注意：必须用 update 触发重新解析 package 仓库；install 只读 composer.lock，不会加载新声明的本地包。
压缩包结构不规范导致安装失败的典型表现
最常见的报错是：Could not find a matching version of package myorg/mylib，或 Failed to extract ...: unable to create directory。根本原因几乎都出在压缩包内容结构上。
- 压缩包里多了一层目录（如
mylib-1.0.0/composer.json）→ Composer 解压后找不到根级composer.json - 压缩包用了相对路径（如通过
zip -r pkg.zip ./src ./composer.json）→ 解压时路径混乱，autoload 失效 -
dist.url写成相对路径（如"url": "mylib.zip"）→ Composer 当作远程 URL 处理，报 404 - zip 文件权限为只读，且运行用户无读取权限 → 静默失败，日志中出现
failed to open stream: Permission denied
验证方式很简单：手动解压到空目录，确认能否直接运行 composer install —— 如果不行，Composer 也一定不行。
