webman与vue3组合开发后台管理系统的核心是静态资源路径对齐、路由分发权归属、接口契约干净：vue需正确配置publicpath/base并部署到public子目录；nginx必须用try_files托管前端路由，而非依赖route::any()；webman后端接口须显式注册restful路径、返回标准json、手动校验token。
Webman 与 Vue3 组合开发后台管理系统，核心不是“能不能跑”，而是「静态资源路径对齐、路由分发权归属、接口契约是否干净」这三件事没理清，90% 的 404、白屏、token 校验失效都源于此。
Vue3 构建产物必须落到 public/ 子目录且 publicPath 严格匹配
Vue CLI 或 Vite 构建后若直接扔进 public/dist，但没改 publicPath，浏览器会去请求 /js/app.xxx.js，而真实路径是 /dist/js/app.xxx.js，必然 404。
- Vite 项目在
vite.config.ts中设base: '/admin/'（若前端部署在/admin/下） - Vue CLI 项目在
vue.config.js中设publicPath: '/admin/'，并确保outputDir指向../public/admin - 构建后手动检查
public/admin/index.html中所有<script></script>和<link>的src/href是否都带/admin/前缀 - 禁止把前端打包目录放在
app/、resources/等 PHP 逻辑目录下——Webman 不托管这些路径的静态文件
Route::any() 不能替代 Nginx 的 try_files
用 Route::any('/admin', fn() => response()->file(public_path().'/admin/index.html')) 只能响应 /admin 这一个 URL；用户刷新 /admin/user/123 时，Webman 根本收不到请求，Nginx 直接返回 404。
使用 `@ainative/vue-sdk` 为 Vue 3 应用添加 AI 聊天功能。适用于以下场景：(1) 安装 `@ainative/vue-sdk`，(2) 在 Vue 组件中使用 `useChat` 组合式函数，(3) 提供……
- 生产环境必须由 Nginx 处理所有前端路由：配置
location ^~ /admin/块，用alias指向public/admin，再加try_files $uri $uri/ /admin/index.html - Webman 的
Route::any()仅建议用于本地开发兜底或调试页，不可用于生产前端路由分发 - 不要在 Webman 路由里写
return response()->file(...)返回 HTML——它不处理 HTML 内部的 JS/CSS 路径重写，也不支持 SPA 的 history 模式回退
接口路径必须显式注册，禁用 ThinkPHP 风格的点号分隔
前端发请求到 /admin/auth.admin/mySelf，Webman 会 404，因为它没有模块自动解析机制，auth.admin 不是合法控制器名，只是字符串。
- 在
app/route.php中显式注册：Route::group('/admin', function () { Route::post('/auth/login', [AuthController::class, 'login']); Route::get('/auth/myself', [AuthController::class, 'myself']); }); - 前端 Axios baseURL 或
VITE_APP_BASE_URL必须同步指向http://127.0.0.1:8787/admin，接口调用路径写成/auth/login即可 - 所有控制器方法必须返回标准 JSON：
return json(['code' => 0, 'data' => $user]);，禁用echo、var_dump、exit - Token 校验不能依赖中间件挂载
$request->user——Webman 的 Request 是 immutable 对象，需在每个接口内手动调用鉴权函数提取并验证
代码生成器输出需手动适配 Webman 生命周期
SaiAdmin 或 likeadmin 的 php webman sai:generate 生成的控制器，默认按 ThinkPHP 风格写，比如用 $this->app->make(UserModel::class) 或依赖注入构造器，但 Webman 默认不自动解析控制器构造参数，也不默认绑定服务到容器。
- 生成后检查控制器构造函数：若含参数，需在
app/bootstrap.php或对应服务提供者中显式绑定，例如Container::set(UserModel::class, fn() => new UserModel()); - 避免在控制器里用
new UserModel()—— 会导致无法 mock 单元测试，也绕过容器生命周期管理 - ORM 实例化优先走容器：
$model = app(UserModel::class);，而非new UserModel() - 协程环境下慎用静态变量缓存数据——Webman 常驻内存，一次请求污染可能影响后续请求
最易被忽略的是：前端路由由 Nginx 托管、后端接口由 Webman 显式定义、两者之间没有隐式约定。任何想“让框架自动猜路径”的尝试，都会在部署时卡住。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
