默认情况下path仓库会复制而非软链接本地包，必须在repositories中显式配置"options": {"symlink": true}，且url需为相对路径、目标有合法composer.json、require中版本写全如"dev-main"。
为什么composer install后本地包没变成软链接？
默认情况下，path类型仓库会把本地目录「复制」进vendor/，不是链接——这是为了构建可重现性，但模块开发时完全没用。你改了源码，composer install还是旧副本。
必须显式启用软链接模式：在repositories配置里加"options": {"symlink": true}。否则哪怕路径对、composer.json合法，也只会复制。
-
url必须是相对路径（如../my-package），不能用~或绝对路径 - 目标目录下必须有合法的
composer.json，且name字段要和require中一致 - 分支名要写全，比如
"dev-main"，不能只写"dev"或省略
chmod对符号链接本身无效，真正要设权限的是目标目录
Linux 下chmod作用于符号链接文件自身（比如vendor/my/package这个链接文件）毫无意义——它只是个 0 字节指针。真正影响运行的是被指向目录里的文件权限，尤其是autoload.php、bin/脚本、以及src/中 PHP 文件的读取权限。
Linux Security Scanner
下载
Linux 安全审计工具，检查 SSH 配置、开放/监听端口、防火墙规则（ufw/iptables/nftables）、失败登录尝试、sudoers 权限...
- 确保目标本地包目录（如
../my-package）对 Web 服务器用户（如www-data）可读：chmod -R 755 ../my-package/src ../my-package/bin - 如果包里有生成缓存或日志的逻辑，其子目录（如
../my-package/storage）需额外设为可写：chown -R www-data:www-data ../my-package/storage - 不要对
vendor/下的符号链接递归chmod -R——既没必要，还可能误改其他依赖的权限
CI/部署时composer link容易静默失败
composer link命令依赖当前用户对目标目录有写权限，且要求目标包已通过composer require安装过。在 CI 或 Docker 中，常因用户切换、UID 不匹配或挂载卷权限限制导致失败，但 Composer 不报错，只是不建链接。
- 确认执行
composer link的用户能写入vendor/（如chown -R $USER:$(id -gn) vendor） - 避免在 CI 中混用
composer link和path仓库——二者机制冲突，后者更稳定 - 若必须用
composer link，先检查是否已安装：composer show vendor/name；再进包目录运行composer link；最后回主项目验证ls -l vendor/vendor/name是否为->指向
PATH 和 autoload 冲突：软链接存在但类找不到
即使符号链接建成了，PHP 自动加载仍可能失败——因为 Composer 的 autoloader 是在vendor/autoload.php生成时静态注册的，它只认vendor/下的真实路径，不自动识别软链接目标的autoload配置。
- 确保本地包的
composer.json里有正确"autoload"段（如"psr-4": {"Vendor\Package\": "src/"}） - 每次修改本地包的
autoload结构后，必须在主项目运行composer dump-autoload刷新映射 - 不要手动编辑
vendor/composer/autoload_psr4.php——它会被下次dump-autoload覆盖
实际操作中最容易被忽略的，是软链接生效后不重新生成 autoload 映射，以及误以为 chmod 链接文件就能控制执行权限。这两点不处理，90% 的“链接了但跑不起来”问题就出在这儿。
