离线安装共享依赖必须用path仓库+COMPOSER_DISABLE_NETWORK=1，直接composer require必失败；需配置合法composer.json、相对路径repositories、禁用全局packagist，并执行dump-autoload -o。
离线安装共享依赖必须用 path 仓库 + COMPOSER_DISABLE_NETWORK=1
直接 composer require 在断网时必然失败，因为 Composer 默认会联网查包名、校验版本、拉取元数据——哪怕你本地磁盘上已有完全一样的代码。唯一可靠路径是把共享依赖目录当成本地仓库用，靠 path 类型绕过所有远程请求。
常见错误现象：Could not fetch https://repo.packagist.org/packages.json 或卡在 Reading composer.json of acme/utils (dev-main)；根本原因不是没网络，而是没显式切断 Composer 的 fallback 行为。
- 目标包根目录下必须有合法
composer.json，含完整"name"（如"acme/utils"）和"version"或分支标识（如"dev-main"） -
repositories段必须显式声明：{"type":"path","url":"./packages/my-utils"}，不能只写packagist: false - 执行前必须设环境变量：
COMPOSER_DISABLE_NETWORK=1（Linux/macOS），Windows CMD 用set COMPOSER_DISABLE_NETWORK=1 && composer require...，PowerShell 用$env:COMPOSER_DISABLE_NETWORK="1" - 安装命令必须带
@dev后缀：composer require acme/utils:@dev，否则不识别本地 path 包
composer.json 里怎么配 path 仓库才不踩坑
很多人写了 repositories 却仍联网失败，问题出在配置细节：Composer 对 path 仓库的解析非常严格，稍有偏差就 fallback 到 Packagist。
-
url值必须是相对路径（如"./packages/utils"），不能是绝对路径（/home/user/packages/utils）或带file://前缀 - 建议在
options中加{"symlink": false}，避免离线机因软链失效导致 autoload 失败 - 务必同步禁用全局 Packagist：
composer config --global repo.packagist false；仅项目级禁用（composer config repo.packagist false）不够，插件或子命令仍可能触发 - 检查是否生效：
composer config repo.packagist输出应为空，而不是composer https://packagist.org
装完为什么 Class not found？必须跑 dump-autoload -o
即使 vendor/acme/utils 目录已存在，且 composer.json 里写了 PSR-4 自动加载规则，不手动重建 autoload 映射，运行时照样报错。Composer 不会在 require 后自动刷新 autoload，尤其对 path 类型包。
- 必须立即执行：
composer dump-autoload -o（-o强制生成优化版映射，比默认散列更稳定） - 如果项目已有大量包，加
--no-dev避免加载 dev-only 类，减少冲突概率 - 验证是否生效：在项目中
require 'vendor/autoload.php'; var_dump(class_exists('Acme\Utils\Helper')); - 注意锁文件污染：
composer.lock里若混了"source": {"type": "git"}条目，离线 install 时会直接失败，需手动清理或重生成
共享依赖目录结构与权限容易被忽略
看似只是复制一个文件夹，但实际涉及路径可移植性、PHP 版本兼容性和符号链接行为，这些在离线环境下无法动态修复。
- 共享包目录建议放在项目内，如
./packages/my-utils，而非用户主目录或系统路径，确保迁移后路径不变 - 目标机器 PHP 版本必须与开发机一致（小版本号也要对齐，如 8.2.12 ≠ 8.2.13），否则某些内部 API 差异会导致
Class not found - 确认目标机已启用必需扩展：
mbstring、openssl、zlib，缺一不可；--ignore-platform-reqs会掩盖这些问题，让错误延后到运行时爆发 - 如果共享包含
bin/脚本（如自定义 CLI 工具），目标机php必须在$PATH中，且路径与源环境一致，否则脚本执行失败
