应配置 artifact 类型仓库并禁用 packagist.org：在 composer.json 的 repositories 中添加 type 为 "artifact"、url 为本地绝对路径的项，并设 "packagist.org": false，否则仍会优先从线上源下载。
怎么让 composer install 从本地目录读包（离线场景）
直接用 artifact 类型仓库，它本质是把一堆已打包的 .tar 或 .zip 文件当私有 Packagist 用。不需要 HTTP 服务，不依赖网络，适合内网、CI 缓存或断网部署。
常见错误是误以为放个 packages.json 就行——其实必须用 composer archive 打包，且结构要严格匹配：每个包一个压缩包，文件名格式为 vendor/name-version.tar（如 monolog/monolog-2.10.0.tar），全部放在同一目录下。
- 确保所有压缩包里包含完整的
composer.json，且name和version字段与文件名一致 - 压缩包内路径不能带根目录（比如不要
/src/...，而应是src/...），否则解压后 autoload 失败 - 运行
composer archive前，先cd进包根目录，否则生成的包会漏文件或路径错乱
如何配置 composer.json 指向本地 artifact 目录
在项目根目录的 composer.json 里加 repositories 配置，类型设为 artifact，值为本地绝对或相对路径（推荐绝对路径，避免 CI 中路径错位）。
典型错误是路径写成 URL（如 file:///path）或用了环境变量未展开（$HOME/artifacts 不生效）。Composer 只认真实存在的文件系统路径。
- 路径末尾不加斜杠，但目录必须存在且可读
- 如果目录下有多个同名包不同版本（如
foo/bar-1.0.0.tar和foo/bar-1.1.0.tar），Composer 会自动选满足约束的最高版本 - 注意权限：PHP 进程用户（如 www-data）必须有该目录的读取权限，否则报
Could not read packages.json
{
"repositories": [
{
"type": "artifact",
"url": "/opt/composer-artifacts"
}
],
"require": {
"monolog/monolog": "^2.10"
}
}
为什么 require 的包还是去 packagist.org 下载了
因为 artifact 仓库只提供元数据，不接管依赖解析逻辑；Composer 仍会按默认顺序查源——先找 packagist.org，没命中才查 artifact。所以必须禁用默认源，或显式声明仅用本地源。
最稳妥做法是在 composer.json 里加 "packagist.org": false 到 repositories 顶层，否则哪怕你配了 artifact，只要 packagist 上有同名包，它就优先走线上。
- 执行
composer install --no-cache避免旧缓存干扰判断 - 用
composer show -s查看当前启用的源列表，确认packagist.org已被禁用 - 如果用了
composer config --global repo.packagist false，会影响所有项目，不推荐；应只在项目级控制
离线环境下更新包版本要怎么操作
artifact 本身不支持“更新”——它只是静态文件集合。想升级某个包，必须手动替换对应压缩包，并确保新包的 name、version、文件名三者完全一致（连大小写、分隔符都不能错）。
容易忽略的是：即使只改了代码，也必须重新运行 composer archive 生成新压缩包。直接改原目录再 tar 是危险的，因为 autoload 信息可能未刷新，或者 composer.json 里的 autoload 配置和实际目录结构不匹配。
- 每次换包前，先删掉旧压缩包，再放新包，避免 Composer 因缓存误读旧版本
- 建议用脚本校验：检查压缩包内
composer.json的name是否等于vendor/name，version是否与文件名中版本一致 - 如果包含 git 依赖（如
"dev-master"），artifact 无法处理——这种必须提前打成具体语义化版本再归档
composer.json 却没同步更新 artifact 目录，install 就会静默失败或装错版本。建议把 artifact 目录纳入 Git（小包）或用 rsync+校验和管理（大包），别靠人肉拷贝。 
