必须修改 composer.json 的 repositories 配置为 artifact 类型并指定本地目录，因 Composer 不支持直接 install 本地压缩包；需将包按 vendor/name-version.zip 格式存放，配置中 url 用相对或绝对路径（不加末尾斜杠），禁用 packagist.org 以优先使用本地包。
用 composer install 从本地压缩包安装依赖，必须改 composer.json 的 repositories
Composer 默认不支持直接指定一个本地 .zip 或 .tar.gz 文件作为包源。想让 composer install 或 composer require 拉取本地压缩包，核心是把本地文件伪装成一个「artifact 仓库」——也就是告诉 Composer：“这个目录里放的全是打包好的 tarball，按包名+版本去匹配”。
关键操作有三步：
- 把压缩包放到一个**固定目录**下（比如
./packages/），文件名必须严格符合{vendor}/{package}-{version}.zip格式，例如monolog/monolog-2.10.0.zip - 在项目根目录的
composer.json中添加repositories配置，类型设为artifact，路径指向该目录 -
require里写明包名和版本（必须与压缩包文件名中的版本一致），然后运行composer update vendor/package或composer install
注意：artifact 仓库只支持 .zip、.tar、.tar.gz、.tgz、.tar.bz2 和 .tbz2，不支持 .7z 或其他格式。
repositories 配置写法和常见错误
正确的 repositories 片段长这样：
{
"repositories": [
{
"type": "artifact",
"url": "./packages/"
}
]
}
容易出错的地方：
-
url必须是**相对路径**（以./开头）或**绝对路径**（如/var/www/myproject/packages/），不能是 HTTP 地址；写成"https://localhost/packages/"会静默失败 - 路径末尾**不要加斜杠**（
"./packages"和"./packages/"在某些系统下行为不一致，推荐统一不加） - 如果项目已启用 packagist.org，默认它排在第一位；要优先走本地 artifact，得把
packagist.org显式禁用："packagist.org": false放进repositories数组顶部 - 压缩包内必须包含合法的
composer.json（在根目录），且其中name和version必须与文件名完全对应
为什么 composer require path/to/file.zip 不行
Composer 没有提供直接安装单个压缩包的命令。你可能会试 composer require ./packages/monolog-2.10.0.zip，结果报错：
Could not find a matching version of package ./packages/monolog-2.10.0.zip.
这是因为 require 后面只能跟 vendor/name 形式的包名，不是文件路径。即使加了 --dev 或指定版本号也无效。真正起作用的是 repositories + require 的组合逻辑：Composer 先查所有仓库，发现 artifact 目录里有匹配的 monolog/monolog-2.10.0.zip，再解压校验，最后安装。
顺带一提：如果你只是临时测试一个修改过的包，用 path 类型仓库更轻量（支持开发模式 symlink），但 artifact 才是离线、可归档、适合 CI 构建的方案。
压缩包内容结构和 composer.json 要求
解压后的目录结构必须满足：
- 顶层是
composer.json（不能在子目录里） -
composer.json中的name字段必须为vendor/name格式，比如"monolog/monolog" -
version字段值必须与压缩包文件名中的版本字符串完全一致（包括-beta、-rc等后缀） - 如果压缩包里有
autoload配置，需确保路径正确；否则安装后可能提示Class not found
举个最小可用的 composer.json 示例（放在 monolog/monolog-2.10.0.zip 内部）：
{
"name": "monolog/monolog",
"version": "2.10.0",
"autoload": {
"psr-4": {
"Monolog\": "src/"
}
}
}
没写 autoload 或路径错，会导致类自动加载失败——这比安装失败更难排查，因为 composer install 会成功，但运行时报 Class 'MonologLogger' not found。
