Composer不支持从ZIP直接安装私有包，但可通过artifact仓库类型实现本地ZIP离线分发：需ZIP命名规范（如acme/utils-1.2.0.zip）、根目录含匹配name字段的composer.json、用composer install而非require，并配置repositories指向ZIP目录。
直接说结论：Composer 不支持从 ZIP 文件直接安装私有包，但可以通过 artifact 仓库类型实现「本地 ZIP 包离线分发」——前提是 ZIP 文件结构合规、命名规范，且必须用 composer install（不能用 composer require 动态添加）。
什么是 Composer 的 artifact 仓库？
这是 Composer 内置的一种只读仓库类型，专为离线或内网环境设计。它不连接 Packagist，也不走 Git/SVN，而是扫描指定目录下所有符合命名规则的 ZIP（或 TAR）文件，提取其中的 composer.json 来构建可用包列表。
关键点：
-
artifact只在composer install或composer update时生效，不会出现在composer show --available中 - ZIP 文件名必须是
{vendor}/{package}[-{version}].zip，例如：acme/utils-1.2.0.zip - ZIP 内部**根目录下必须包含有效的
composer.json**，且该文件里的name字段要与文件名中的vendor/package严格一致 - 不支持 ZIP 内嵌子目录（如
acme-utils-1.2.0/src/...），必须扁平化：解压后直接看到composer.json、src/、tests/等
如何生成合规的 ZIP 包？
手动打包极易出错，推荐用脚本确保结构。核心是：先清理构建目录，再复制源码 + composer.json，最后压缩。
以 PHP 包 acme/utils 为例（假设当前在项目根目录）：
mkdir -p build/artifact cp composer.json build/artifact/ cp -r src/ tests/ build/artifact/ cd build/artifact zip -r ../acme/utils-1.2.0.zip . cd ../.. rm -rf build/artifact
注意：
- 不要用 GUI 压缩工具（如 macOS 归档实用工具），它们常带
__MACOSX/或隐藏文件，会破坏校验 -
composer.json中的version字段可省略（ZIP 文件名已声明版本），但name和autoload必须正确 - 如果包依赖其他私有包，那些依赖也得提前准备好 ZIP 并放入同一 artifact 目录，否则
install会失败
如何配置项目使用 artifact 仓库？
在项目的 composer.json 根对象中添加 repositories，指向 ZIP 所在目录（**必须是绝对路径或相对于 composer.json 的相对路径**）：
{
"repositories": [
{
"type": "artifact",
"url": "./artifacts/"
}
],
"require": {
"acme/utils": "^1.2.0"
}
}
然后执行：
composer install
常见错误：
-
Could not find package acme/utils at any version→ 检查 ZIP 文件名是否匹配、composer.json中name是否拼写一致、目录路径是否可读 -
Invalid zip file, cannot determine version→ ZIP 内无composer.json，或它不在根目录 -
Package acme/utils has a PHP requirement incompatible with your PHP version→ 不是 artifact 问题，是composer.json中require.php声明太新，需调整
为什么不能用 composer require 添加 artifact 包？
因为 composer require 默认走 Packagist 元数据查询，而 artifact 是纯本地扫描机制，不提供远程元数据接口。它只在锁文件存在或运行 install/update 时，根据 composer.lock 中记录的 ZIP 路径和哈希值进行校验和解压。
所以正确流程是：
- 先确保 ZIP 已放在
url指定目录 - 在
composer.json的require中手动写入包名和版本约束 - 运行
composer install（不是require）生成锁文件
一旦 composer.lock 生成，后续 composer install 就能复用 ZIP，无需网络、无需 Git —— 这正是 artifact 的价值所在。
最容易被忽略的是 ZIP 文件名与 composer.json 中 name 的双向一致性，以及 artifact 对锁文件的强依赖。没锁文件，就等于没包。
