Webman路由404问题主因是Web服务器伪静态未生效或路由未注册：一查Nginx try_files规则与root路径；二验route:list输出；三检PHP-FPM的PATH_INFO传递；四看route_must强制路由是否拦截静态资源。
如果您在使用Webman框架部署应用后访问路由地址返回404错误，但入口文件index.php可正常加载，则问题极大概率出在Web服务器伪静态配置未生效或Webman路由注册未被正确触发——请求根本未进入Webman的PHP路由分发层，而非路由定义本身有误。以下是多种可独立验证与执行的排查与修复方法：
一、检查Nginx伪静态规则是否完整且已重载
Nginx必须将所有非静态资源请求（如 /api/user、/admin/dashboard）显式转发至Webman入口文件public/index.php，否则将直接返回404。关键在于location块中必须包含try_files指令，且不能遗漏$uri/部分；若使用rewrite方式，则需确保last标志与正则捕获完整性。
1、登录服务器，打开对应站点的Nginx配置文件（路径通常为/www/server/panel/vhost/nginx/域名.conf或/etc/nginx/conf.d/域名.conf）。
2、定位到server块内的location /配置段，确认其内容符合Webman官方推荐格式：
location / { try_files $uri $uri/ /public/index.php?$query_string; }
3、若当前规则为rewrite ^(.*)$ /public/index.php?s=$1 last;，请替换为上述try_files写法——rewrite在Nginx 1.21+版本中与某些fastcgi_param组合存在兼容性风险，优先使用try_files。
4、保存配置后，在终端执行nginx -t验证语法；若提示“syntax is ok”，再执行nginx -s reload强制重载。
5、使用curl命令验证是否进入PHP层：curl -I http://your-domain.com/api/test，若响应头中出现X-Powered-By: Webman，说明已成功接管；若仅返回Server: nginx且无该字段，则仍处于Nginx直返阶段。
二、确认Webman运行目录与Nginx root路径严格一致
Webman要求Nginx的root指令必须指向项目根目录下的public子目录，而非整个项目根目录。若root设置为/www/wwwroot/myapp，而实际入口为/www/wwwroot/myapp/public/index.php，Nginx将无法定位到index.php，导致全部动态路由404。
1、在宝塔面板中进入【网站】→点击目标站点【设置】→【网站目录】选项卡。
2、检查【网站根目录】字段值是否为完整绝对路径，且末尾包含/public，例如/www/wwwroot/myapp/public。
3、若当前显示为/www/wwwroot/myapp或为空，请手动修改为带/public的完整路径。
4、特别注意：不能填写相对路径（如public）、不能漏掉开头斜杠、不能多加斜杠（如//public）。
5、点击【保存】后，必须返回【网站】列表页对该站点执行【重启】操作（非【重载配置】），因Nginx的root指令变更需进程级重启才生效。
三、验证Webman路由是否已实际加载并注册
即使Web服务器配置正确，若Webman自身路由未在启动时完成注册，或注册位置错误（如写在条件分支中、位于中间件内、或被缓存固化），也会导致route:list命令无输出、所有自定义路径均返回404。
1、进入项目根目录，执行命令：php webman route:list。
2、若输出为空、仅显示默认/static路由、或缺失您定义的/api/*等规则，则说明路由未加载。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
3、检查路由定义文件位置：Webman标准路由应统一写在app/route.php中，且该文件必须被start.php或bootstrap/app.php主动引入。
4、确认无以下干扰行为：未在app/route.php顶部添加 'v1']，却访问/api/user）。
5、清空运行时缓存：rm -rf runtime/container/ runtime/cache/ runtime/log/，然后重启Webman服务：php start.php restart。
四、检查PHP-FPM是否正确传递PATH_INFO变量
Webman依赖$_SERVER['PATH_INFO']解析路由路径段（如/api/user中的/api/user）。若Nginx未通过fastcgi_param显式设置该变量，或设置值为空，则框架无法提取真实请求路径，一律视为未匹配路由而返回404。
1、在Nginx站点配置的location ~ \.php$块内，查找是否存在以下两行：
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
2、若缺失第一行，请在include fastcgi.conf之后、fastcgi_pass之前手动添加；若已存在但值为""或$request_uri，请更正为$fastcgi_path_info。
3、确认fastcgi_split_path_info指令已启用且正则正确，典型配置为：
fastcgi_split_path_info ^(.+\.php)(/.+)$;
4、修改后再次执行nginx -t && nginx -s reload，并用var_dump($_SERVER['PATH_INFO']);在public/index.php头部临时打印验证值是否为预期路径。
五、排查静态资源拦截与强制路由冲突
当Webman开启强制路由模式（'route_must' => true）后，所有未显式定义的路径（包括/favicon.ico、/robots.txt、/static/css/app.css）均被拦截并返回404，这并非配置错误，而是安全策略生效表现。
1、打开config/app.php，搜索route_must，确认其值是否为true。
2、若需放行常见静态资源，请在app/route.php最顶部添加显式通配规则：
Route::rule(':path^.*\.(js|css|png|jpg|gif|ico|svg|woff|woff2|ttf|eot)$', 'static/:path', 'GET');
3、同时确保该规则在所有Route::get()或Route::post()之前注册，避免被后续更宽泛的路由覆盖。
4、若项目使用CDN或Nginx直接托管静态资源，应在Nginx配置中添加独立location ~* \.(js|css|png|jpg)$块，并配置expires 1y;与add_header Cache-Control "public, immutable";，使静态请求完全绕过PHP层。
