Composer如何建包_Composer创建自定义包步骤【详解】

能被别人 composer require 安装的包必须满足三要素

能被别人 composer require 安装的包必须满足三要素：Packagist 四项必填字段（name、type、autoload、license）全合规；PSR-4 命名空间、目录结构、类名严格一致并执行 composer dump-autoload -o；Git 打带 v 前缀的语义化标签（如 v1.0.0）且推送至远程，首次提交后须在 Packagist 页面手动点击 Update 按钮同步。

想发布一个能被别人顺利 composer require 安装的包？事情可没你想的那么简单——写完 PHP 类只是第一步。真正决定成败的，是 Packagist 的元数据规范、Git 标签规则和 PSR-4 自动加载契约这三道关卡。任何一环出了纰漏，结果要么是别人根本装不上，要么就是装上了却报 Class not found，让人一头雾水。

composer.json 必填字段怎么设才不被 Packagist 拒绝

首先得明确一点：Packagist 不会接受一个仅仅“看起来像包”的项目。它有四个硬性字段必须正确填写：name、type、autoload 和 license。其中，name 和 autoload 是错误高发区。

• name 字段：必须采用全小写的 vendor/name 格式（例如 myorg/my-utils）。关键在于，vendor 部分必须与你注册 Packagist 时的用户名完全一致。包含大写字母、下划线或点号都会导致提交直接被拒。
• type 字段：这里最好明确写成 "library"。别留空，也别填成 project——Packagist 会直接跳过非 library 类型的项目。
• autoload 字段：至少需要配置 psr-4。键必须是完整的命名空间，并以双反斜杠结尾（例如 "MyOrg\MyUtils\": "src/"），而值必须指向一个真实存在的相对目录。这里一个常见的坑是：末尾多一个斜杠或少一个反斜杠，都可能导致后续类加载彻底失败。
• license 字段：这个字段不能为空。可以填写 MIT、Apache-2.0、GPL-3.0 等标准的 SPDX 标识符，但必须写全称且格式正确（例如写 "MIT"，而不是 "mit" 或 "mit license"）。

PSR-4 映射为什么总报 Class not found

遇到 Class not found 错误，十有八九问题出在 PSR-4 映射上。这通常不是命名空间写错了，就是目录结构没对齐。PSR-4 是严格的字符串匹配规则，对大小写、斜杠和文件名三者的一致性要求近乎苛刻。

• 目录结构必须精确匹配：假设你在 composer.json 中配置了 "MyOrg\MyUtils\": "src/"，那么 src/ 目录下就必须存在 MyOrg/MyUtils/ 这样的子目录结构。写成 src/myorg/myutils/ 是不行的，尤其是在 Linux 这类大小写敏感的系统上。即便在 Windows 上暂时能跑，也可能因为缓存旧路径而埋下隐患。
• 类名与文件名必须一致：这是另一个高频错误点。例如，类定义为 class Calculator，那么它所在的文件就必须命名为 Calculator.php。叫成 calc.php 或 calculator.php 都会导致自动加载器找不到它。
• 别忘了更新自动加载器：每次修改 composer.json 中的 autoload 配置后，都必须运行 composer dump-autoload 命令，否则新的映射关系不会生效。对于本地开发和测试，强烈建议加上 -o 参数来生成优化后的加载器：composer dump-autoload -o。
• 区分生产与开发依赖：不要把 tests/ 或 bin/ 这类目录塞进 autoload.psr-4。它们应该被归入 autoload-dev 部分，否则你的生产环境可能会无缘无故加载测试代码，带来不必要的开销和潜在问题。

Git tag 怎么打才能让别人 require 到正式版本

这里有个关键认知：Packagist 根本不关心你 composer.json 里写的 version 字段。它只认 Git 标签（tag）。没有标签，就等于没有版本；标签格式错了，也跟没发布一样。

• 标签格式必须规范：必须使用带 v 前缀的语义化版本标签。正确操作是运行 git tag v1.0.0，而不是 git tag 1.0.0。像 v1.0、dev-main、feature/foo 这样的标签，Packagist 都不会将其识别为有效版本。
• 标签必须推送到远程仓库：打了本地标签后，一定要推送到远程：git push origin v1.0.0。或者，你也可以一次性推送所有标签：git push origin --tags。如果标签只存在于本地，Packagist 是根本看不到的。
• 首次提交后的关键一步：当你第一次将包提交到 Packagist 后，页面上通常会显示“This package is not auto-updated”。这时，你必须手动点击右上角的 Update 按钮，Packagist 才会去拉取你已经推送的 Git 标签。
• 如何修复已发布的错误版本：如果你发现代码有问题，想用同一个版本号重新发布，需要先删除远程标签：git push origin :v1.0.0，然后删除本地标签：git tag -d v1.0.0，最后再重新打标签并推送。

私有包怎么让自己的项目装得上

私有包不会出现在公共的 Packagist 上，因此，你需要在使用方项目中明确告诉 Composer：“去哪儿找这个包”。这依赖于在 composer.json 中配置 repositories 字段，而不是去修改私有包本身的配置。

• 配置版本库：在使用方项目的根目录 composer.json 中，添加如下配置："repositories": [{"type": "vcs", "url": "https://gitlab.internal/myorg/my-logger"}]。这里 type 推荐使用 vcs，而不是 package（后者维护成本高，容易出错）。
• 处理仓库认证：如果 Git 仓库需要认证，切记不要把凭证直接写在 composer.json 里。正确做法是使用 auth.json 文件来管理，并且务必将其权限设置为 600（命令：chmod 600 ~/.composer/auth.json），以确保安全。
• 私有包也需要打标签：即使是私有包，也必须打上符合规范的标签（如 v1.0.0）。否则，当你运行 composer require myorg/my-logger 时，默认只会拉取 dev-main 分支，这既不稳定，也无法保证构建的可重现性。
• 本地调试技巧：在本地开发调试阶段，可以使用 path 类型的仓库来快速验证：{"type": "path", "url": "../my-logger"}。但切记，在上线前，一定要切换回 vcs 方式。

最后，再强调一个最容易被忽略的细节：当你首次在 Packagist 提交包之后，页面上显示的状态并不是“已发布”，而是“未自动更新”。如果你不手动点击那个 Update 按钮，那么无论你的标签推送得多么及时、仓库多么公开、配置多么正确，别人都无法通过 composer require 安装到你的包。这一点，务必警惕。