必须设"type": "library"，因该包是供他人require的可复用组件；设为project或自定义类型会导致packagist/laravel自动发现失效、ci误判及功能不可用。
明确区分“库”和“项目”，从 composer.json 类型开始
你的包是供别人 require 的可复用组件，不是最终运行的网站或应用——这决定了整个设计起点。错把扩展包当项目配置，会导致后续所有维护动作失焦。
必须设 "type": "library"，而非 "type": "project" 或随意写 "type": "laravel-package"。Packagist 和 Laravel 自动发现机制都依赖这个字段做语义判断；设错后，Laravel 10+ 可能直接跳过注册，且 CI 工具会误判兼容性。
常见错误现象：composer require your/package 成功但 Facade 不可用、php artisan vendor:publish 找不到资源、Laravel Dusk 测试里 Class not found。
- 如果提供服务提供者（Service Provider），确保它继承
thinkService（ThinkPHP）或IlluminateSupportServiceProvider（Laravel），且register()和boot()中不执行副作用逻辑（如 DB 查询、HTTP 调用） - 避免在
extra中滥用laravel.dont-discover：留空或不声明即可启用自动发现；显式设为true会彻底关闭 - 不要在
conflict里写"laravel/framework": " 这类宽泛限制——它会让所有 Laravel 10+ 用户无法安装；精确到已知崩溃的小版本，例如 <code>"laravel/framework": "11.0.5"
PSR-4 自动加载必须严格对齐，且启用 --strict-psr 检查
Composer 2.0+ 在 optimize-autoloader 模式下会跳过非标准路径映射。你本地 composer dump-autoload 能跑通，不代表 CI 或下游项目能加载成功。
正确配置示例：
{
"autoload": {
"psr-4": {
"YourVendor\YourPackage\": "src/"
}
}
}
关键点：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
src/下不能有src/YourVendor/YourPackage/嵌套结构——那属于 PSR-0 风格，与 PSR-4 冲突 - 命名空间末尾必须带反斜杠
，否则 Composer 解析时可能拼接错误路径 - CI 流水线中加一步：
composer dump-autoload --strict-psr && php -l src/*.php，提前拦截命名空间与文件路径不一致问题
版本约束要“对下游宽松，对自己严格”
你作为包作者，控制的是 require 和 require-dev；但真正影响下游是否能装上的，是你声明的依赖范围是否合理。
典型反例："monolog/monolog": "^2.0" —— 当用户项目强制要求 ^3.0 时，Composer 直接报 Root requirements could not be resolved，而不是降级或兼容。
实操建议：
- 运行
composer outdated --direct查当前直接依赖是否过期，但别盲目升级；主版本号变化（如^2.9 → ^3.0）必须人工验证破坏性变更 - 对运行时强依赖（如
topthink/framework、illuminate/support）用"^8.0 || ^9.0"这类多段范围，而非单版本锁死 - 对开发时才用的工具（如
phpunit/phpunit、laravel/pint）必须放在require-dev，否则生产环境会多装几十 MB 无用代码，还可能触发冲突
发布前必须打语义化 tag，且禁用 dev-main 引用
任何文档、README 或同事协作中出现 "your/package": "dev-main"，都是不可接受的风险信号。Packagist 不索引 dev- 分支，且 minimum-stability 设置稍有偏差就会导致 Could not find package。
正确流程：
- 完成开发并测试通过后，执行
git tag v1.3.0 && git push --tags -
composer.json中确保有"minimum-stability": "stable"和"prefer-stable": true，这是 Packagist 解析稳定性的依据 - 本地验证：删掉
vendor/和composer.lock，运行composer require your/package:^1.3，确认能正常 autoload、注册、运行
最易被忽略的一点：tag 名称必须是纯语义化版本（v1.3.0），不能带额外后缀（如 v1.3.0-beta）。Composer 默认只认 vX.Y.Z 格式，否则下游 ^1.3 将无法匹配到该版本。
