如何在 Composer 中配置一个 artifact 类型的仓库来安装本地 zip 包？

Composer 配置 artifact 仓库可从本地 ZIP 安装私有或离线包，要求 ZIP 根目录含 composer.json，通过 repositories 指定 ZIP 所在目录，安装时按 name 和 version 匹配并解压到 vendor。

在 Composer 中配置 artifact 类型仓库，是为了让项目能从本地 ZIP 文件安装包（比如未发布到 Packagist 的私有包、离线环境下的预构建包，或临时测试用的打包版本）。它不依赖网络源，直接读取本地 ZIP 文件并解析其 composer.json 内容。

1. 准备符合要求的 ZIP 包

Composer 的 artifact 机制要求 ZIP 文件内部必须包含一个有效的 composer.json 文件，且该文件需位于 ZIP 根目录下（不能嵌套在子文件夹中）。例如：

• my-package-1.0.0.zip 解压后结构应为：
  composer.json
src/...
tests/...
• ZIP 文件名建议遵循 {vendor}/{package}-{version}.zip 格式（如 acme/utils-2.1.0.zip），Composer 会从中提取 vendor、package 和 version 信息；若命名不规范，可通过 ZIP 内部 composer.json 的 "name" 和 "version" 字段补全。

2. 配置 artifact 仓库路径

在项目的 composer.json 中添加 repositories 配置，指定存放 ZIP 文件的本地目录（支持绝对路径或相对于 composer.json 的相对路径）：

{
    "repositories": [
        {
            "type": "artifact",
            "url": "./packages/"
        }
    ],
    "require": {
        "acme/utils": "^2.1"
    }
}

登录后复制

上面例子中，Composer 会扫描 ./packages/ 目录下所有 ZIP 文件（包括子目录），匹配所需包和版本。注意：url 必须是目录路径，不是单个 ZIP 文件路径。

标签： composer js json ai 解压 常见问题