webman静态文件404因public目录路径不匹配、static.php中enable设为false、staticfile中间件未启用、中文路径未urldecode或/app/路径误用所致，需逐一排查并修正对应配置。
如果您尝试访问 Webman 项目中的静态文件（如 /upload/avatar.png），但返回 404 错误，则可能是由于 public 目录未被正确识别、路由拦截覆盖或中文路径未解码 所致。以下是解决此问题的步骤：
一、确认静态文件存放位置与访问路径匹配
Webman 默认仅从 {主项目目录}/public 目录提供静态文件服务，所有请求路径均映射至此目录下的真实文件。若文件实际位于其他路径（如 /storage 或 /app/public），将无法被自动解析。
1、检查目标文件是否真实存在于 {主项目目录}/public/ 下，例如访问 /upload/avatar.png 时，需确保该路径对应物理文件 {主项目目录}/public/upload/avatar.png 存在且可读。
2、确认文件权限为 644（Linux/macOS）或无系统级读取限制（Windows）。
3、使用命令行进入项目根目录，执行 ls -l public/upload/avatar.png 验证文件存在性与权限状态。
二、检查静态文件支持是否被手动关闭
若在 config/static.php 中将 enable 选项设为 false，Webman 将完全禁用静态文件中间件，所有静态资源请求均返回 404。
1、打开 config/static.php 文件。
2、查找 'enable' => false 行，将其修改为 'enable' => true。
3、保存文件后重启 Webman 服务（如使用 php start.php restart）。
三、验证静态文件中间件是否启用并配置正确
Webman 的静态文件处理依赖于 app/middleware/StaticFile.php 中间件，该中间件需在 config/static.php 的 middleware 数组中显式启用，否则不生效。
1、打开 config/static.php，定位到 middleware 键。
2、确认其值包含 support\middleware\StaticFile::class，例如：'middleware' => [support\middleware\StaticFile::class]。
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
3、若缺失，将其添加至数组开头位置；若存在但被注释，请取消注释。
4、重启服务使中间件加载生效。
四、排查中文文件名导致的 404 问题
Webman 原生未对请求路径执行 urldecode()，当访问含中文的静态文件（如 /upload/头像.png）时，$path 参数仍为 URL 编码格式（如 %E5%A4%B4%E5%83%8F.png），直接拼接文件路径将导致 is_file() 判断失败。
1、打开 vendor/workerman/webman-framework/src/App.php。
2、定位到 findFile() 方法内部。
3、在 $file = "$public_dir/$path"; 上方插入 $path = urldecode($path);。
4、保存后重启服务，确保中文路径能被正确还原为 UTF-8 字符串后再进行文件查找。
五、检查应用插件路径混淆引发的 404
以 /app/xx/ 开头的请求会被 Webman 自动重定向至对应插件的 public 目录，而非主项目的 public/app/ 子目录。若误将静态文件放在此类路径下，将因插件不存在或插件未注册而返回 404。
1、确认请求 URL 是否以 /app/ 开头（如 /app/demo/style.css）。
2、若非插件资源，请立即将文件移出 /app/ 路径，改放至主项目 public/ 下对应位置（如 public/demo/style.css）。
3、若确属插件资源，请检查插件是否已通过 config/plugin.php 正确注册，并确认插件目录内存在 public/ 子目录及目标文件。
