根本原因是 composer.json 中 "name" 字段格式非法，必须为全小写、两段式（vendor/name）、仅含字母数字和短横线且不以分隔符开头或结尾；应改为如 "yourname/my-app" 并运行 composer validate 验证。

Composer 报错 “No matching package found” 且提示 Root package name is invalid

根本原因不是包不存在，而是当前项目根目录下的 composer.json 中 "name" 字段格式不合法。Composer 要求 Root 包的 name 必须是 vendor/name 格式（如 myorg/myproject），不能是单个单词、带空格、大写字母、下划线或以点开头等。

• 常见非法写法："name": "my-project"（缺少 vendor 段）、"name": "MyProject"（含大写）、"name": "project_v1"（含下划线）、"name": ".myapp"（以点开头）
• 合法示例："name": "acme/my-website"、"name": "john-doe/blog-api"
• 如果你只是本地开发、不发布到 Packagist，vendor 部分可任意取（如 local/dev），但格式必须满足 foo/bar 两段式、全小写、仅含字母数字和短横线
• 改完后运行 composer validate 确认语法和命名合规；再执行 composer install 或 composer update

为什么 composer create-project 后也报这个错？

因为某些模板项目（尤其旧版 Laravel、Symfony 脚手架）生成的 composer.json 默认把 "name" 设为类似 "laravel/laravel" —— 这在 Packagist 上是合法的，但当你用它初始化一个新项目时，Composer 会把它当作“已发布的包”来解析，而你本地并没有注册该 vendor，导致后续依赖解析失败。

• 解决方法：立即修改 name 为你自己的标识，例如从 "laravel/laravel" 改成 "yourname/my-new-app"
• 同时检查 "description"、"type"（建议设为 "project"）字段是否合理，避免被误判为库包
• 如果项目原本是 fork 或 clone 的，注意删掉 "autoload" 里可能残留的 "psr-4" 映射（比如指向原作者命名空间），否则自动加载也会出问题

composer.json 中 name 字段到底有哪些硬性限制？

Composer 内部使用 Composer\Package\Loader\RootPackageLoader 解析 root 包，对 name 做正则校验：/^[a-z0-9]([_.-]?[a-z0-9]+)*\/[a-z0-9]([_.-]?[a-z0-9]+)*$/i。也就是说：

• 必须有且只有一个 /，前后都不能为空
• 每段只能由小写字母、数字、短横线（-）、点（.）、下划线（_）组成
• 但开头和结尾不能是 .、-、_，也不能连续出现两个以上分隔符（如 -- 或 ._）
• 实际最安全做法：只用小写字母、数字、短横线，且每段以字母开头（如 my-org/my-tool）

{
    "name": "my-org/my-new-app",
    "type": "project",
    "description": "A fresh PHP application",
    "require": {
        "php": "^8.1"
    }
}

修复后仍提示 “Root package not found in repo” 怎么办？

这通常是因为 Composer 缓存了旧的、非法的 composer.json 解析结果，或者当前目录不是真正的项目根目录（比如你在子目录里执行了 composer install）。

• 先确认你在项目最外层目录（即包含 composer.json 的那个目录）执行命令
• 运行 composer clear-cache 清除本地缓存
• 临时重命名 vendor/ 和 composer.lock，再重新 composer install
• 如果用了自定义 COMPOSER 环境变量或 --working-dir 参数，检查路径是否指向了错误位置

名字不规范这个问题，表面看是格式错误，实际影响的是整个依赖解析链路的起点判断——一旦 root 包名不合法，Composer 就无法构建正确的包上下文，后续所有操作都可能失效。很多人卡在这里反复重装、换镜像，其实只需要改一行 name。