切面类未被扫描到：需确认config/autoload/annotations.php中scan.scan_dirs是否包含切面目录（如app\aspect），且切面类必须带#[aspect]注解、非abstract/final，运行php bin/hyperf.php di:dump验证是否出现在输出中。
切面类没被扫描到：先确认路径和注解是否“看得见”
Hyperf 的 AOP 不是自动全局生效的，它依赖注解扫描器发现 #[Aspect] 类。如果切面类压根没进容器，后续所有排查都白搭。
- 检查
config/autoload/annotations.php中的scan.scan_dirs是否包含你的切面目录，比如App\Aspect；漏写或拼错命名空间都会导致跳过 - 切面类必须带
#[Aspect]注解（不是@Aspect），且该类本身不能是abstract或final - 运行
php bin/hyperf.php di:dump，搜索你的切面类全名（如App\Aspect\TraceAspect）——如果没出现在输出里，说明扫描失败 - 别信 IDE 自动补全：PHP 8.0+ 属性类型提示（如
public TraceAspect $aspect;）不触发扫描，必须显式加#[Inject]或其他 DI 注解才能被识别为可注入目标
代理类没生成：检查容器注册和缓存是否“新鲜”
即使切面类被扫描到，Hyperf 还要生成代理类并注册进 DI 容器。这一步卡住，process() 永远不会执行。
- 确认
config/autoload/dependencies.php中已注册Hyperf\Aop\AspectContainer::class，否则切面管理器不启动 - 修改切面类后必须清缓存：执行
php bin/hyperf.php di:clear+php bin/hyperf.php di:dump，否则旧代理逻辑仍在运行 - 在切面类里加个
#[PostConstruct]方法，打印日志，例如：log->info('TraceAspect loaded');—— 如果没输出，说明它根本没成为 Bean - 注意
scan.ignore_annotations配置：如果误把Aspect加进忽略列表，注解会被直接跳过
目标方法没被拦截：看切入规则是否“够得着”
切面类活了，不代表它能拦到你想织入的方法。匹配逻辑是精确的，通配符写错一个字符就失效。
-
$classes数组写法要严格匹配类名+方法名格式，例如IndexController::class . '::index'，不能写成'IndexController::index'（缺::class会导致字符串拼接失败） - 用通配符时注意层级：写
'App\Controller\*Controller::*'能匹配App\Controller\UserController下所有 public 方法；但写成'App\Controller\*::*'可能因命名空间嵌套过深而漏掉 - 目标方法必须是 public，且不能是
final、static或构造函数——这些方法无法被代理重写 - 如果用注解方式拦截（如
$annotations = [Trace::class]），确保目标方法上确实用了该注解，且该注解类已正确声明#[Attribute(Attribute::TARGET_METHOD)]
实际运行时看不到效果：验证代理是否真在调用链中
最隐蔽的问题是：切面加载了、代理生成了、规则也匹配了，但你调用的却不是代理对象。
- 在控制器或服务里直接
new TraceAspect()或$this->traceAspect（未通过 DI 获取）——这绕过了代理机制，process()不会触发 - 检查目标类是否被
@Controller、@Service等注解标记；没被容器管理的类，Hyperf 不会给它套代理 - 开启 Hyperf 的调试模式（
SWOOLE_HTTP_DEBUG=1），观察日志里是否有Aop: proxy class generated for ...类似提示；没有则说明代理未生成 - 临时在切面
process()开头加var_dump(debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2));，确认调用栈是否来自你预期的业务入口
scan_dirs 路径配置错误——它们不报错，只让一切停在第一步。
