必须将插件中topthink/framework的require声明改为与主项目完全一致的版本格式（如"6.3."），禁用"^"或""等宽松约束，并通过composer require --with-all-dependencies强制同步依赖，同时提交composer.lock确保团队安装版本一致。
团队协同开发ThinkPHP插件时，必须确保每个成员安装的扩展版本与主框架行为完全一致，否则会出现钩子不触发、中间件跳过、事件监听失效等静默故障——这类问题往往在测试环境才暴露，修复成本远高于预防成本。
插件依赖必须与主项目框架版本对齐
打开插件项目的 composer.json 文件，将 topthink/framework 的 require 声明改为与主项目完全一致的写法，例如主项目锁在 "topthink/framework": "6.3.*"，插件也必须写成相同形式。
不能写 "^6.0" 或 "*"，否则 Composer 会按自身解析规则选择兼容版本，可能装上 6.2.x 而主项目是 6.3.8——ThinkPHP 6.3 中模型的 afterWrite 事件触发时机与 6.2 不同，插件里写的监听逻辑就会漏执行。
这一步操作起来很简单，直接修改 JSON 字段后保存即可。
立即学习“PHP免费学习笔记（深入）”；
发布前强制验证依赖兼容性
在主项目根目录下执行以下命令，强制将插件以开发态载入并同步升级其全部依赖：
composer require vendor/plugin-name:dev-develop --with-all-dependencies
注意：必须加 --with-all-dependencies 参数，否则 Composer 只更新插件顶层依赖，忽略其子依赖与主项目的冲突校验。
如果命令报错“cannot resolve”，说明插件内部某子包仍引用了旧版框架（如 "topthink/think-orm": "^2.0"），需进入插件源码逐个修正其 composer.json 中所有框架相关依赖项。
统一提交 composer.lock 到 Git
第一步：确认插件项目根目录存在 composer.lock 文件；
第二步：执行 git add composer.lock；
第三步：提交时注明“lock: pin all deps to match main project v6.3.8”；
第四步：推送至远程仓库。
【未提交 composer.lock 将导致其他成员执行 composer install 时拉取随机小版本】 比如有人装上 6.3.1，有人是 6.3.7——两者虽同属 6.3 分支，但 6.3.5 起调整了中间件异常捕获顺序，插件中依赖该行为的错误处理逻辑就会失效。
接口文档与代码保持同步
方法一：在插件控制器方法的 PHPDoc 注释块中，用 Swagger 标签声明接口参数与响应结构，例如：@OA\Post(path="/api/v1/plugin/submit", @OA\RequestBody(...))；
方法二：使用 php think api:build 命令自动生成 Markdown 文档，输出到 docs/api/plugin.md；
每次插件新增或修改接口，必须同步更新对应注释或重新运行生成命令——文档滞后于代码是跨团队协作中最常见的沟通断层点。
