必须先配置国内镜像源，否则composer create-project会卡在“Loading composer repositories”；因packagist.org国内物理不可达，且config -g repo.packagist命令需严格满足键名、type值、URL末尾斜杠、用户权限四要素，缺一即静默失效。
不配镜像就跑 composer create-project，99% 会卡在 “Loading composer repositories” —— 不是网络差，是 packagist.org 在国内物理不可达。
为什么 composer config -g repo.packagist 总是不生效
这条命令静默失败时完全不报错，但配置根本没写进去。常见原因有四个：
-
repo.packagist写成repos.packagist或packagist.org：键名必须严格为单数小写repo.packagist - 漏掉中间的
composer（它是type值，不是可选参数）：正确格式是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - URL 少了末尾斜杠
/：会导致请求路径拼成https://mirrors.aliyun.com/composerpackages.json，404 后直接降级回官方源 - 执行用户权限不对：Windows 没重启终端、Linux/macOS 用
sudo运行导致写入 root 配置，而当前用户读不到
验证是否真生效：运行 composer config -g repo.packagist，输出必须是完整 JSON，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null 或纯字符串，说明没写对，立刻重试。
项目初始化前必须做的三件事
别等 create-project 卡住才补救。新 API 项目初始化本质是拉全量元数据 + 解析依赖树，每一步都依赖镜像可用：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 先清旧缓存：
composer clear-cache（尤其之前失败过，缓存可能残留损坏索引） - 确认目标目录名合法：不能含中文、空格、大写字母或特殊字符（如
My API或api_v2!），否则create-project可能中途报Could not delete - 临时加参数救急：哪怕全局没配好，也能用
--repository-url强制走镜像，例如composer create-project laravel/laravel api-demo --repository-url=https://mirrors.aliyun.com/composer/
composer create-project 必带的四个加速参数
Laravel、Lumen 或自建 API 框架初始化时，create-project 实质是一次完整 install。不加参数，默认行为会拖慢 3–5 倍：
-
--prefer-dist：跳过 git clone，强制下载 ZIP 包（国内 CDN 加速明显） -
--no-dev：API 项目初期不需要phpunit、phpstan等开发依赖，省去冲突解析和下载 -
--optimize-autoloader：生成静态类映射，避免后续autoload.php扫描大量文件 -
--no-interaction：防止交互式提示阻塞自动化流程（CI/CD 场景下必加）
完整命令示例：composer create-project laravel/laravel api-demo --prefer-dist --no-dev --optimize-autoloader --no-interaction
项目级配置比全局更可靠，尤其在 CI 和协作中
GitHub Actions、GitLab CI、宝塔面板默认以 runner 或 www 用户运行，它们根本读不到你本地用户的 ~/.composer/config.json。项目级配置一提交就同步，行为可预期：
- 进项目根目录，执行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不带-g） - 该命令会在
composer.json顶层自动写入"repositories"字段，key 固定为"packagist"，不会覆盖已有私有源 - 如果项目已有
"repositories": []数组结构，命令会失败；此时需手动编辑，确保 JSON 合法（尤其末尾不能多逗号） - 改完后删掉
vendor/和composer.lock，再跑composer install，否则 lock 文件仍指向海外源
真正容易被忽略的是：镜像只加速元数据拉取和 ZIP 下载，不解决 Resolving dependencies 卡顿。如果卡在这里，问题一定出在 composer.json 的 PHP 版本约束太宽、require-dev 堆太多工具链，或者用了已废弃的 fxp/composer-asset-plugin —— 换任何镜像都没用。
