本地包安装卡住主因是Composer误判路径类型或权限受限：需确保path仓库明确定义、composer.json含固定version字段、路径可读且无循环软链，Windows需禁用symlink或改用dist方式，宝塔/Docker环境须用绝对路径并修正用户权限与SELinux设置。
本地包安装卡住，90% 不是路径或语法问题，而是 Composer 误判为远程源、跳过缓存校验、或权限/符号链接被拦截。
composer require path/to/local/package 卡在 Resolving dependencies
这个阶段根本不发网络请求，换镜像没用。卡在这里说明 Composer 正在递归扫描你指定的本地路径，但路径里有循环软链、不可读子目录，或 composer.json 缺少 version 字段（必须显式声明，不能靠 Git tag 或分支名）。
- 先验证路径可读：
ls -la path/to/local/package，确认当前用户有执行权限（目录需x），且composer.json存在并可读 -
version必须是固定字符串，如"1.0.0"，不能写"dev-main"或留空；否则 Composer 会尝试解析分支，触发 Git 操作 - 避免路径含空格或中文；Windows 下优先用 WSL 或确保路径用正斜杠
/，不要用\ - 若本地包本身依赖其他包，且那些包又指向另一个本地路径，容易形成解析环——临时注释掉嵌套的
path类型仓库再试
卡在 Loading from cache 或 Downloading 后无响应
Composer 看到 path 类型仓库时，默认仍会尝试从缓存加载或走 HTTP 回退逻辑，尤其当 composer.json 中同时定义了 repositories 数组且含远程源时，它可能错误地把本地路径当成远程 URL 的别名去请求。
- 强制禁用远程回退：
composer require --no-cache --ignore-platform-reqs path/to/local/package - 删掉项目
composer.json里所有repositories配置项（哪怕只是注释），只保留require中的path行 - 检查是否启用了
apcu或opcache缓存了旧的解析结果：临时加-d apc.enable_cli=0 -d opcache.enable_cli=0再运行命令 - Windows 用户注意：杀毒软件常拦截
symlink()调用，而 Composer 在path模式下默认创建符号链接。改用"symlink": false显式关闭：composer config --local repositories.local '{"type":"package","package":{"name":"vendor/name","version":"1.0.0","dist":{"url":"file:///full/path/to/local/package.zip","type":"zip"}}}'（即改用 dist 方式）
vendor/ 下生成的是拷贝而非链接，且后续 update 失败
这说明 Composer 没识别出 path 类型，而是当作普通包处理了——通常因为路径不是绝对路径，或未启用 path repository 类型。
-
path类型必须明确定义在repositories中：{ "repositories": [ { "type": "path", "url": "./packages/my-local-package" } ], "require": { "my-vendor/my-local-package": "*" } } - URL 必须是相对路径（以
./开头）或绝对路径（以/开头），不能是../向上越界（Composer 会拒绝） - 确保
my-local-package目录下有合法composer.json，且name字段与require中完全一致（包括大小写） - 首次安装后，
vendor/my-vendor/my-local-package应是符号链接（Linux/macOS）或目录重解析（Windows）。如果不是，说明path仓库未生效，检查composer diagnose输出中是否有Invalid repository type "path"提示（旧版 Composer 不支持）
宝塔或 Docker 中执行失败，报 Permission denied 或 No such file
容器或面板环境默认以非交互用户（如 www 或 www-data）运行命令，它无法读取你个人账号下的相对路径，也常被 SELinux 或挂载选项限制符号链接。
- 路径必须写成绝对形式，且对目标用户可读：
"url": "/www/wwwroot/example.com/packages/my-local-package" - 宿主机上先修复归属：
sudo chown -R www:www /www/wwwroot/example.com/packages/ - Docker 中确保挂载时加
:Z（SELinux）或:rshared（符号链接穿透），例如：-v $(pwd)/packages:/app/packages:Z - 宝塔计划任务里，命令前加
cd /www/wwwroot/example.com &&，避免工作目录错位导致相对路径失效
真正难调的点往往不在路径写法，而在环境对符号链接和文件系统权限的隐式限制——先确认 ls -l vendor/ 看是不是真实链接，再查 id 和 getenforce（SELinux）或 sestatus，比反复改 composer.json 有效得多。
