Composer如何加载离线zip包：本地压缩包加载配置详解
如果你尝试过在离线环境下使用 composer require vendor/name 来加载一个本地的 ZIP 包，大概率会碰壁。核心原因其实很明确：Composer 默认只查询 Packagist 官方仓库，如果不显式配置 repositories 为 package 或 artifact 类型，它根本不会去识别你放在本地的 ZIP 文件。 结果就是，命令直接报错 Could not find package，让人误以为是缓存或路径问题。
为什么 composer require vendor/name 会失败？
这得从 Composer 的工作机制说起。默认情况下，它的视线只投向 Packagist，并不会主动扫描你的本地文件系统。所以，即便你把精心准备的 utils-1.2.0.zip 放在了项目根目录，Composer 也会视而不见——这并非缓存未清理，而是仓库发现机制本身就没有启用。
那么，解决方案就是明确告诉 Composer 去哪里找。主要有两种仓库类型可供选择：
artifact类型：最适合处理现成的 ZIP 包，比如从 Nexus 私有库导出的，或者团队内部归档的版本。它只认文件名，不关心 ZIP 包内部是否包含composer.json。package类型：这种方式需要你在配置中手动写明包的名称、版本和下载路径。它支持file://协议或相对路径，但要求 ZIP 包内必须包含一个有效的composer.json文件。- 这里有个常见的误区：别试图用
path类型来加载 ZIP 压缩包，它只接受解压后的目录。
artifact 配置怎么写才不报错？
这种方式配置起来相对直观。首先，建议将所有离线 ZIP 包集中放置在一个目录下，例如 ./packages。然后，在项目的 composer.json 文件中进行如下声明：
{
"repositories": [
{
"type": "artifact",
"url": "./packages"
}
],
"require": {
"myorg/utils": "1.2.0"
}
}
配置虽简单，但魔鬼藏在细节里。最关键的一点是：ZIP 文件的命名必须严格遵守 {vendor}-{name}-{version}.zip 的格式。 例如，myorg/utils-1.2.0.zip 是正确的，而 utils-v1.2.0.zip 或 myorg_utils_1.2.0.zip 都会导致加载失败。
另外几个需要注意的坑：
url字段填写的是目录路径，而不是具体的 ZIP 文件路径。- 在
require中指定版本时，不支持^1.2这类范围约束，必须写死具体的版本号，如"1.2.0"。 - 如果执行
composer install时提示No zip archive found，别急着怀疑人生，先检查一下文件名的大小写或者版本号后面是不是多了一个不起眼的空格。
package 方式更适合哪些场景？
如果说 artifact 是“认名不认人”，那么 package 方式就更像是一次完整的身份验证。当你需要对目标包进行更精细的控制时，比如修改其自动加载规则、设置分支别名，或者确保其平台配置准确，package 方式是更可靠的选择。
它的核心要求是：ZIP 包内必须包含一个合法的 composer.json 文件，至少要有 "name" 和 "version" 字段。配置示例如下：
{
"repositories": [
{
"type": "package",
"package": {
"name": "myorg/utils",
"version": "1.2.0",
"dist": {
"url": "./packages/utils-1.2.0.zip",
"type": "zip"
},
"autoload": {
"psr-4": {
"MyOrg\\Utils\\": "src/"
}
}
}
}
]
}
这种方式优势明显：
- 下载路径（
dist.url）非常灵活，可以使用file://协议，也可以直接用相对路径。 - 支持更复杂的版本别名写法，例如
"version": "dev-main as 1.2.0"。 - 当然，代价是它比
artifact多了一层元数据校验，构建速度会稍慢一些。
离线安装后为什么仍连外网？
这是另一个让人头疼的问题：明明配置了本地仓库，执行 composer install 时却依然发现它在尝试连接外网。这通常发生在两种情况下：一是执行了 composer update 命令，二是没有完全禁用 Packagist 的回退（fallback）机制。
要打造一个真正纯净的离线环境，可以按以下步骤操作：
- 彻底关闭 Packagist：运行
composer config --global repo.packagist false。这是最根本的一步。 - 慎用 update 命令：在离线环境下，尽量避免使用
composer update，因为它需要联网解析最新的依赖关系树。锁定版本后，使用install即可。 - 验证网络隔离：一个简单的验证方法是，临时将
127.0.0.1 repo.packagist.org加入系统的 hosts 文件，再运行composer install。如果看到Connection refused之类的错误，才证明网络请求被成功阻断了。
最后，还有一个极易被忽略的陷阱：如果你使用 package 方式加载的 ZIP 包，其内部的 composer.json 文件还 require 了其他第三方包，而这些依赖包并没有被同时放入你的本地仓库，那么 Composer 可能会静默失败——它不会报错，但最终 vendor 目录里会缺失这些依赖。因此，确保依赖链条的完整性，是离线部署成功的关键。
至于设置环境变量 COMPOSER_DISABLE_NETWORK=1，它确实是一个强力开关，但更像是一剂“猛药”，可能会掩盖配置上的其他缺陷，不建议作为长期依赖的解决方案。
