从零开始搭一个 WordPress 插件：我的目录结构、入口文件与本地调试环境踩坑实录

刚开始写插件那会儿，我把所有代码塞进一个 zsens-admin.php，前端后端、AJAX、短代码全挤在一起，调试时改一行崩三处。后来拆过三个商业插件的源码，才理解目录结构不是"规范强迫症"，是降低调试认知负担的刚需。这篇记录我现在的脚手架，以及本地环境怎么配才能"秒级复现问题"。

一、我的目录结构：按"加载阶段"分层，不是按"功能类型"

很多教程教你按 admin/、public/、includes/ 分，我早期也这么干。但实际开发中，你更常问的是"这段代码在哪个生命周期跑"，而不是"这是前端还是后端"。所以我改成了按加载时序组织：

zsens-admin/
├── zsens-admin.php          # 入口：只做"是否该加载"的判断
├── bootstrap/
│   ├── loader.php             # 类自动加载器（PSR-4 简化版）
│   └── dependencies.php       # 检查 PHP/WP 版本、依赖插件
├── early/
│   ├── constants.php          # 定义常量（必须在插件加载前可用）
│   └── mu-fallback.php        # 若需 MU 插件模式时的兼容入口
├── hooks/
│   ├── register-activation.php
│   ├── register-deactivation.php
│   └── register-uninstall.php
├── core/
│   ├── Plugin.php             # 主类： orchestration，不干事
│   ├── Admin.php              # 后台相关钩子聚合
│   ├── Frontend.php           # 前台相关钩子聚合
│   └── Ajax.php               # AJAX 端点注册（注意：注册≠处理）
├── modules/                   # 实际功能模块，按需懒加载
│   ├── user-levels/
│   │   ├── class-user-levels.php
│   │   └── assets/            # 模块级资源，不堆到全局
│   └── community-bridge/
│       └── ...
├── vendor/                    # Composer 依赖（提交 lock，不提交 vendor 到 SVN）
└── tests/
    ├── phpunit/
    │   └── bootstrap.php      # 加载 WP 测试框架
    └── e2e/
        └── playwright.config.js

关键变化：core/ 里的类只负责"什么时候挂载什么"，具体实现下沉到 modules/。这样调试时，我先看 Plugin.php 的 run() 方法就能定位问题阶段，不用在 2000 行代码里翻。

二、入口文件：越薄越好，但要防"直接访问"和"重复定义"两种死法

我的 zsens-admin.php 现在长这样，注释比代码多：

Zsens Admin 需要 PHP 7.4+