Composer autoload 必须使用 PSR-4，因其支持模块化热加载和自动命名空间映射；classmap 会导致硬编码路径、需手动刷新，违背即插即用原则。
Composer autoload 配置必须用 psr-4，别碰 classmap
PSR-4 是唯一能支持模块化插件热加载、命名空间自动映射的机制；classmap 会把所有类硬编码进 autoload_classmap.php，一旦插件目录变动或新增类，就必须手动 composer dump-autoload，违背“模块即插即用”原则。
实际配置示例（composer.json）：
{
"autoload": {
"psr-4": {
"Plugin\HelloWorld\": "src/Plugin/HelloWorld/"
}
}
}
- 命名空间前缀必须以
\结尾（如Plugin\HelloWorld\），否则 Composer 解析失败 - 路径值必须是相对于
composer.json的相对路径，不能以/开头 - 多个插件共存时，每个插件需独立声明自己的命名空间前缀，避免冲突
插件入口文件统一放在 src/Plugin/{Name}/Plugin.php
这是被大多数 WordPress / Typecho / DokuWiki 等中文生态插件系统识别的标准入口约定。Composer 不负责加载它，但脚手架要预留可被宿主系统 require 的稳定路径。
该文件必须返回一个实现标准接口的实例（如 PluginInterface），而非直接执行逻辑：
<?php
namespace PluginHelloWorld;
<p>class Plugin implements PluginInterface
{
public function init(): void { /<em> ... </em>/ }
public function getName(): string { return 'HelloWorld'; }
}
return new Plugin();</p>- 不要在
Plugin.php中调用require_once或include，依赖全部走 autoloader - 不要 echo/print_r 任何内容——插件初始化阶段输出会破坏 HTTP header 或 JSON 响应
- 若宿主系统要求函数式入口（如 WordPress 的
plugin_name_activation()），应在Plugin.php中注册钩子，而非定义全局函数
composer.json 的 type 字段必须设为 wordpress-plugin 或自定义类型
虽然 Composer 官方不强制校验 type，但中文插件市场（如 WPJAM、Typecho 插件仓库）和 CI 构建工具依赖它做分类与部署判断。设成 library 或留空会导致插件包被忽略或误判为 SDK。
- WordPress 插件推荐使用
"type": "wordpress-plugin"，并配合extra.wp-plugin-dir指定主文件名（如hello-world.php） - Typecho 插件建议设为
"type": "typecho-plugin"，并在extra中声明plugin-id和plugin-version - 自研框架可定义私有 type（如
myapp-module），但需同步更新对应 loader 的 type 匹配逻辑
开发时禁用 vendor/composer/autoload_static.php 缓存
默认情况下 Composer 生成静态加载器提升性能，但它会固化类路径映射——你在 src/ 下新增一个类，autoload_static.php 不会自动更新，导致新类“找不到”。开发阶段必须关掉它。
- 运行
composer install --no-autoloader+ 手动composer dump-autoload是最稳妥方式 - 或在
composer.json中加"optimize-autoloader": false（仅限 dev 环境） - CI 流水线里仍应启用优化（
--optimize-autoloader），但本地开发务必保持动态 autoload
这个点最容易被忽略：你改了类、跑了 composer dump-autoload，却还是报 Class not found，大概率是静态 autoload 缓存没清干净，或者 IDE 没刷新 vendor 目录索引。
