推荐用 composer create-project 初始化扩展包，因其预置合法 name、autoload 路径和 PHP 版本约束，可规避 90% 高频错误；而 composer init 缺乏关键校验，易致 Packagist 发布失败。
用 composer create-project 而不是 composer init 初始化包结构
直接手敲或交互式 composer init 容易漏掉 Packagist 强制校验项，导致后续发布失败。比如 name 字段必须是 vendor/name 格式（不能是 myapp），autoload 的 PSR-4 路径末尾必须带斜杠（"src/"，不是 "src"），require 里必须显式声明 PHP 版本（如 "php": "^8.1"）。
推荐命令：
composer create-project php-pkg/skeleton my-utils --no-interaction
执行后立刻进目录运行：
composer dump-autoload -o
这样生成的 composer.json 已预置 "type": "library"、合法命名空间映射和 PHP 版本约束——不是“可选”，是 Packagist 接收和本地 require 正常工作的硬门槛。
src/ 目录结构与命名空间必须严格对齐 PSR-4
自动加载失败的最常见原因不是代码写错，而是路径和命名空间不匹配。例如你在 composer.json 中写了：
"autoload": { "psr-4": { "AcmeUtils\": "src/" } }
那就意味着：
-
src/Helper.php对应类名必须是AcmeUtilsHelper -
src/Http/Client.php对应类名必须是AcmeUtilsHttpClient - 文件名大小写必须与类名完全一致（Linux 下敏感，Windows 可能掩盖问题）
别在 src/ 下再建 src/ 子目录；也别把类放在 src/ 根下却用 AcmeUtilsSubnamespaceClass 命名——PSR-4 是路径即命名空间，没中间层转换逻辑。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
本地开发时用 path 仓库方式测试，别急着 git push 和提交 Packagist
在主项目中测试扩展包功能前，先在主项目的 composer.json 里加 repositories：
"repositories": [
{
"type": "path",
"url": "../my-utils"
}
]
然后运行：
composer require acme/utils:dev-main
这样 Composer 就会软链接本地目录，改 my-utils/src/ 里的代码，主项目立刻生效，无需反复 git commit → push → composer update。等所有功能跑通、单元测试通过，再推远程、打 tag、提交 Packagist。
注意：dev-main 中的 main 要和你本地仓库的默认分支名一致（Git 2.28+ 默认是 main，旧版可能是 master）。
发布前必须验证的三件事：命名、版本、稳定性
Packagist 不接受任何模糊配置。提交前务必确认：
-
name在 https://packagist.org/packages/vendor/name页面返回 404（未被占用） -
composer.json中有明确的"minimum-stability": "dev"或"stable"，且没有"prefer-stable": true冲突项 - 已打 Git tag，格式为
v1.0.0（带v前缀），且该 tag 已git push --tags上去
漏掉任意一项，Packagist 都会静默拒绝同步，或者别人 composer require 时提示 Could not find package acme/utils——错误信息不提示具体原因，只能回查配置。
