Webman与Vue/React集成的关键在于静态资源路径对齐、Nginx兜底路由配置及开发代理正确设置：Vue需配outputDir和publicPath，React需设homepage并移动build目录；/vue-app/*等前端路由必须由Nginx通过try_files指向index.html，而非仅依赖Route::any()；开发时必须用Vite/Vue CLI proxy代理API请求，禁用PHP错误输出以确保JSON响应纯净。
Webman 与 Vue/React 集成不是“配个路由就能跑”，关键在静态资源路径、构建产物归宿、以及开发时的跨域代理是否真正解耦——否则你会反复遇到 404、Failed to load resource 或 Cannot GET /xxx。
Vue/React 构建产物必须落到 public/ 下指定子目录
Webman 的静态资源由 public/ 目录直接托管，不经过 PHP 路由。这意味着你不能把 Vue/React 的 index.html 和打包 JS/CSS 放在任意位置，否则 Nginx/Apache 会直接 404。
常见错误：Vue 项目用默认 outputDir: 'dist'，然后手动复制到 public/vue-app，但忘了改 publicPath —— 导致 JS 请求地址仍是 /js/app.xxx.js，而实际路径是 /vue-app/js/app.xxx.js，浏览器加载失败。
- Vue 项目需在
vue.config.js中显式配置：module.exports = { outputDir: '../public/vue-app', publicPath: '/vue-app/' } - React 项目需在
package.json中设"homepage": "/react-app"，并自定义build脚本，确保构建后整个build/被移动到public/react-app - 构建后检查
public/vue-app/index.html中的 script 标签 src 是否都带/vue-app/前缀；否则前端白屏且控制台报 404
Route::any() 路由只负责兜底，不替代静态服务
很多人以为加一条 Route::any('/vue-app', function () { return response()->file(public_path() . '/vue-app/index.html'); }); 就能“接管”整个 Vue 应用 —— 这是错的。该路由只响应 /vue-app 这一个路径，而 Vue Router 的 history 模式下，用户刷新 /vue-app/user/123 时，Webman 并不会自动重写为 /vue-app/index.html，Nginx 会直接返回 404。
立即学习“PHP免费学习笔记（深入）”；
正确做法是：让 Web 服务器（Nginx）处理所有 /vue-app/* 请求，全部指向 public/vue-app/index.html，PHP 路由完全不参与前端路由分发。
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
- Nginx 配置片段示例：
location ^~ /vue-app/ { alias /path/to/your/webman/public/vue-app/; try_files $uri $uri/ /vue-app/index.html; } - Webman 自身的
Route::any()路由建议仅用于调试或 fallback 页面，生产环境应交由 Nginx 处理 - 若坚持用 PHP 路由兜底，需匹配通配路径如
/vue-app/(.*)并统一返回index.html，但性能和可靠性不如 Nginx
开发时跨域问题必须用前端代理，而非后端开 CORS
Vue CLI 或 Vite 的 devServer.proxy 是开发阶段唯一靠谱的跨域方案。你在 Webman 后端配 CORS 头，对开发环境无效，因为浏览器请求的是 http://localhost:3000/api/users，根本没走到 Webman；它只在生产部署后、前后端同域或你手动访问 Webman 接口时才起作用。
典型误操作：一边在 Vue 的 vite.config.ts 里写了 proxy，一边又在 Webman 的中间件里加 Access-Control-Allow-Origin: *，结果发现开发时还是跨域 —— 因为 proxy 已把请求转发给 Webman，但 Webman 返回的响应头被浏览器忽略（因预检失败或 header 冲突）。
- Vue/Vite 开发代理必须指向 Webman 实际监听地址，例如：
server: { proxy: { '/api': { target: 'http://localhost:8787', // Webman 默认端口 changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } - Webman 后端无需、也不应为开发环境开启全局 CORS；仅当生产需支持第三方调用 API 时，才按需配置
fruitcake/laravel-cors类似中间件（Webman 可用webman/cors） - 代理配置后，前端代码中请求仍写
/api/users，不要写完整 URL
前后端通信的数据格式和错误边界必须对齐
Webman 默认返回 HTML，而 Vue/React 的 axios.get() 默认期望 JSON。一旦后端某处抛出未捕获异常、输出了 PHP Warning、或 echo 了调试字符串，前端就会收到非 JSON 响应，触发 SyntaxError: Unexpected token < in JSON at position 0 —— 这是最隐蔽也最常发生的集成断裂点。
这不是框架问题，是 PHP 输出控制没做好。
- 所有 API 接口必须显式设置头：
header('Content-Type: application/json; charset=utf-8');，并在json_encode()前调用ob_end_clean()清空可能存在的缓冲输出 - 禁用 PHP 错误显示：
ini_set('display_errors', '0');或确保 php.ini 中display_errors = Off，否则错误信息会混在 JSON 前面 - 统一错误结构，例如返回
{"code":500,"message":"数据库连接失败"}，前端用拦截器统一处理，而不是靠try/catch捕 JSON 解析错误 - Webman 的
response()->json()是安全的，但如果你手写echo json_encode(...)，务必确认前面没有任何输出（包括 BOM、空格、print_r()）
真正卡住人的从来不是“怎么连上”，而是构建路径没对齐、开发代理没生效、或者一行 var_dump() 让整个 JSON 崩溃。这些点不提前踩一遍，上线前两小时你还在翻 404 和 SyntaxError。
