Packagist被墙或访问慢时，应优先切换为腾讯云等可靠镜像源；若内网隔离则需自建私有源，推荐Satis或Private Packagist，同时严格规范composer.json字段与版本标签。
Packagist被墙或访问慢时，composer install 卡住怎么办
直接换镜像源是最快速的缓解手段，但本质没解决私有包托管问题。国内用户常遇到 composer install 卡在 https://packagist.org/packages.json 或提示 Connection timed out，这不是 Composer 本身的问题，而是 DNS 污染或 TLS 握手失败导致。临时方案是切到国内镜像：
- 全局替换（仅限开发环境）：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（已停用）或改用https://packagist.laravel-china.org（注意该站已于 2023 年下线） - 更可靠的是用腾讯云、阿里云维护的镜像：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/ - 若公司内网完全无法出外网，镜像也无效——此时必须自建私有源，而非继续折腾代理或 hosts
用 Satis 搭建轻量私有 Packagist 替代服务
Satis 是最贴近 Packagist 原生行为的 PHP 私有源方案，它不提供 Web 界面和实时包提交，而是通过静态 JSON 文件聚合 Git 仓库中的 composer.json，适合中小团队做内部组件分发。
- 安装：
composer create-project composer/satis:dev-main --stability=dev --no-interaction（注意：PHP 8.1+ 推荐用dev-main分支，2.x版本已停止维护） - 配置
satis.json时，repositories必须写完整 Git URL（如https://gitlab.example.com/internal/log-lib.git），不能只写组织名；require-all设为true才会拉取所有 tagged 版本 - 生成命令：
php bin/satis build satis.json ./web/，输出目录需由 Web 服务器可访问（如 Nginx 配置root /path/to/web） - 客户端使用：
composer config repositories.internal composer https://satis.example.com/，之后require的包名必须与 Git 仓库中composer.json的name字段严格一致
私有包无法 composer require 成功的常见原因
即使 Satis 服务跑起来了，composer require internal/log-lib 仍可能报 Could not find package internal/log-lib，问题通常不在网络，而在元数据匹配逻辑。
-
composer.json中的name字段含非法字符（如大写字母、下划线），Packagist 规范要求全小写 + 连字符，例如internal/log-lib合法，InternalLogLib或internal_log_lib会导致 Satis 解析失败 - Git 仓库未打语义化 Tag（如
v1.0.0、1.2.3），Satis 默认只收录带 tag 的 commit；本地测试可用"minimum-stability": "dev"+"prefer-stable": false临时拉dev-master，但生产环境禁用 - Composer 客户端缓存了旧的
packages.json，执行composer clear-cache再试；若用的是自定义域名，确认 DNS 已生效且 HTTPS 证书有效（Satis 不接受自签名证书）
比 Satis 更可控的替代：Toran Proxy 已停更，推荐 Private Packagist 或自研简单代理
Toran Proxy 曾是热门选择，但它已于 2021 年终止维护，PHP 7.4+ 下运行异常，且不再接收安全更新。目前较现实的路径只有两条：
- 付费方案：
Private Packagist（官方出品）支持细粒度权限控制、审计日志、自动同步 GitHub/GitLab，适合中大型团队；但它的composer.json配置方式与 Packagist 完全兼容，迁移成本低 - 极简自研：用 Nginx +
proxy_pass转发请求到 Packagist，并在响应头中注入X-Private-Source: true，再配合 Composer 的http-basic认证拦截非白名单域名请求——这种方案不生成索引，只作流量守门员，适合已有成熟 Git 权限体系的公司 - 注意：所有方案都绕不开一个事实——私有包的
autoload自动加载规则、psr-4命名空间映射、以及replace/provide的冲突处理，这些逻辑仍在 Composer 客户端本地执行，服务端只管分发元数据
真正卡点往往不在搭建，而在于团队对 composer.json 字段含义的理解是否统一，比如 type 写成 library 和 metapackage 会导致依赖解析行为完全不同；还有人误以为私有源能绕过 license 检查——其实 composer install 仍会校验 license 字段是否在 config.allow-plugins 白名单内。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
