插件目录"搭积木"式起步：我用一个最小可运行结构理清了入口文件、自动加载与本地热调试的关系

刚开始写插件那会儿，我直接把 index.php 当入口塞了一堆逻辑，结果激活时白屏，找半天才发现 WordPress 根本不走这文件。后来才明白插件的"门面"是文件头注释，不是某个固定文件名。

现在我的起步目录长这样，够小但能跑：

my-plugin/
├── my-plugin.php          ← 真正入口，文件头让 WP 识别
├── composer.json          ← 仅用于本地 autoload，不打包
├── src/
│   ├── Bootstrap.php      ← 挂钩子、启容器
│   ├── Admin/
│   │   └── MenuPage.php
│   └── Frontend/
│       └── Shortcode.php
├── assets/
│   ├── css/
│   └── js/
└── .vscode/
    └── launch.json        ← Xdebug 监听配置

入口文件我只干三件事：声明、防直访、抛给 Bootstrap：

注意 __FILE__ 必须传，plugin_dir_url(__FILE__) 和 plugin_dir_path(__FILE__) 全靠它定位。我早期用 __DIR__ 拼路径，搬到子目录测试时资源全 404。

Bootstrap 里我用一个静态方法集中挂载，避免在全局空间散钩子：

public static function init(string $mainFile): void
{
    static::$baseFile = $mainFile;
    static::$baseUrl  = plugin_dir_url($mainFile);
    static::$basePath = plugin_dir_path($mainFile);

    add_action('admin_menu', [Admin\MenuPage::class, 'register']);
    add_action('init', [Frontend\Shortcode::class, 'register']);
}


本地调试我不用 var_dump 了，直接上 Xdebug + VS Code。launch.json 关键就这一段：

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}"
    }
}


配合 LocalWP 或 Docker 时，路径映射容易踩坑。我的土办法：在入口文件顶部 error_log(__FILE__)，看日志里的绝对路径，原样填进 pathMappings 左边。

还有个省时间的技巧：装 wp-env 做隔离测试环境，.wp-env.json 指定插件路径映射，npm run wp-env start 后自带调试端口转发，不用手动配 nginx。缺点是冷启动慢，适合验证激活/卸载流程，不适合高频改代码。

你们本地调试是 Docker、LocalWP、还是直接 Vagrant？路径映射有没有被坑过？