composer如何通过本地压缩包安装依赖_artifact路径配置详解【实操】

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 也一定不行。