Webman 适配 Vue3 后台需后端提供标准 RESTful 接口，路径须显式注册（如 /admin/auth/login），禁用 ThinkPHP 风格点号分隔；控制器返回 JSON，手动校验 token，避免不可变 Request 注入 user；代码生成器输出需适配容器绑定或手动实例化；IO 操作需规避协程阻塞，注意长生命周期导致的静态变量污染。
Webman 作为常驻内存的 PHP 高性能框架，本身不处理前端路由或组件渲染，它只负责接收 HTTP 请求、执行业务逻辑、返回 JSON（或 HTML）。所以所谓“Webman 适配 Vue3 后台”，本质是：后端提供标准 RESTful 接口，前端 Vue3 应用通过 axios 或 fetch 调用；两者完全解耦，靠约定的路径、参数、状态码和数据结构协同。
接口路径必须显式声明模块前缀，不能沿用 ThinkPHP 的点号分隔
常见错误现象：http://127.0.0.1:8787/admin/auth.admin/mySelf 返回 404 或 500 —— 这是典型的 ThinkPHP6 多应用风格路径（auth.admin 表示 auth 模块下的 admin 控制器），但 Webman 没有“模块自动解析”机制，它只认真实注册的路由。
正确做法是手动定义清晰的 REST 路径：
- 在
app/route.php中显式注册：Route::group('/admin', function () { Route::post('/auth/login', [AuthController::class, 'login']); Route::get('/auth/myself', [AuthController::class, 'myself']); }); - 前端请求地址必须同步改为
/admin/auth/login和/admin/auth/myself，不能保留.分隔符 - 所有控制器方法需返回标准 JSON 响应，例如：
return json(['code' => 0, 'data' => $user]);，避免直接echo或var_dump
权限控制不能依赖中间件“自动注入用户”，需在每个接口内校验 token
Vue3 前端通常使用 JWT 或 session ID 存于 localStorage / cookie，每次请求带 Authorization header 或 X-Token。Webman 不像 Laravel 自动解析并挂载 $request->user()，你得自己做。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。
- 写一个通用的鉴权函数，比如
AuthHelper::checkToken($request)，从 header 或 query 中提取 token，验证签名、过期时间、角色字段 - 在需要保护的接口里手动调用：
$user = AuthHelper::checkToken($request); if (!$user) return json(['code' => 401, 'msg' => 'Unauthorized']); - 不要试图在全局中间件里“统一赋值
$request->user”，因为 Webman 的Request对象是不可变的（immutable），无法动态添加属性
代码生成器输出的控制器需手动适配 Webman 的生命周期和依赖注入
SaiAdmin 的 php webman sai:generate 会生成 ThinkORM/Eloquent 风格的控制器，但 Webman 默认不启用服务容器自动注入（除非你显式配置了 support\Container）。
容易踩的坑：
- 生成的代码里若有
public function __construct(UserService $service)，运行时会报Class UserService does not exist—— 因为 Webman 默认不扫描注解或自动绑定 - 解决方案：要么改用构造函数参数手动 new 实例（
$this->service = new UserService();），要么在config/container.php中显式绑定：UserService::class => \support\Container::getInstance()->get(UserService::class) - 数据库操作尽量用
Db::table('user')->where(...)->select()替代模型静态调用，减少对 ORM 初始化流程的依赖
文件上传、Excel 导出等 IO 操作要避开协程阻塞，尤其 Windows 下
Webman 默认使用 Select 事件循环（Windows）或 Libevent（Linux），不原生支持异步 IO。像 fopen、file_get_contents、PHPExcel::load() 这类同步操作会阻塞整个进程。
关键处理点：
- 上传文件后，不要立刻用
move_uploaded_file()写入磁盘再读取分析 —— 改为先$_FILES['file']['tmp_name']直接传给解析库（如PhpSpreadsheet\Reader\Xlsx） - 导出 Excel 时，禁用
ob_start()和flush()，改用response()->withHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')->withBody(new Stream($content)) - 若必须耗时操作（如大文件压缩），用
Process启子进程异步执行，主进程立即返回任务 ID，前端轮询结果
最易被忽略的是：Webman 的 start.php 是长生命周期入口，任何全局变量、静态属性、单例对象在多次请求间会复用。Vue3 后台频繁刷新或并发请求时，若你在控制器里写了 static $cache = [] 或缓存了未清理的 DB 连接，就会出现数据污染或连接泄漏。别依赖“每次请求都是干净的”。
