问题根源是服务器未正确加载index.html文件，需依次检查：根目录路径匹配、默认首页配置（index index.html）、子路径的base设置、安全规则拦截及文件权限（755/644且属主为www）。
如果您部署 Vue 或 React 等单页应用后，所有页面（包括首页）均返回 404 错误，则问题通常并非路由配置本身，而是服务器根本未正确加载 index.html 文件。这表明请求未抵达前端入口，而是被服务器判定为路径不存在。
一、检查服务器根目录与文件实际位置是否匹配
该步骤用于确认静态资源是否真实存在于服务器指定路径中。Linux 系统严格区分大小写，且 Nginx/Apache 的 root 或 DocumentRoot 指令决定了请求解析的起始点。若上传的 index.html 实际位于 /www/wwwroot/myapp/dist/index.html，但服务器配置指向 /www/wwwroot/myapp，则所有请求都将失败。
1、登录宝塔面板，进入网站设置，查看「网站目录」中「根目录」路径是否与您上传构建产物的物理路径完全一致。
2、通过宝塔文件管理器或 SSH 进入该根目录，确认是否存在名为 index.html 的文件，且文件名拼写、大小写无误。
3、在浏览器中直接访问 https://your-domain.com/index.html（显式带 .html 后缀），若仍 404，说明服务器未找到该文件；若可打开，则问题出在默认索引配置或重写规则。
二、验证默认首页配置是否启用
服务器需明确告知：当用户访问目录（如 /）时，应自动尝试加载 index.html。若此机制被禁用或覆盖，将导致根路径请求直接 404。
1、在宝塔面板中打开网站设置，切换至「配置文件」选项卡。
2、查找 Nginx 配置中的 location / 块，确认其中包含 index index.html; 行。
3、若使用 Apache，在 .htaccess 或虚拟主机配置中检查是否存在 DirectoryIndex index.html 指令。
三、排查子路径部署缺失 base 配置
当项目部署在非根路径（例如 https://example.com/admin/）时，前端构建产物必须声明公共基础路径，否则所有 JS/CSS 资源引用将从根目录发起请求，全部 404。
1、检查项目根目录下的 vue.config.js（Vue）或 vite.config.ts（Vite）中是否设置了 base: '/admin/'（末尾必须带斜杠）。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
2、重新执行构建命令（如 npm run build），确认 dist 目录中生成的 index.html 内部 script 标签 src 属性前缀是否已变为 /admin/js/app.xxxx.js。
3、在宝塔中将构建产物整体上传至子目录（如 /www/wwwroot/example/admin/），并确保该子目录被正确映射为可访问路径。
四、确认 Nginx/Apache 是否拦截或重定向了所有请求
某些安全插件、伪静态规则或反向代理配置可能意外屏蔽或改写原始请求，使 index.html 无法响应。
1、在宝塔网站设置中关闭「防跨站攻击（Open_basedir）」临时测试，排除其干扰。
2、检查「伪静态」选项卡内容，若存在自定义规则，暂时清空并保存，观察 404 是否消失。
3、在 Nginx 配置中搜索是否有类似 return 404; 或 deny all; 的指令作用于 location / 范围内。
五、验证文件权限与所有权
即使文件存在且路径正确，若 Web 服务进程（如 www 用户）无读取权限，Nginx/Apache 将拒绝提供服务并返回 404（而非 403）。
1、在宝塔文件管理器中选中 dist 目录及内部所有文件，右键「属性」，确认「数字权限」为 755（目录）和 644（文件）。
2、确认文件所有者为 www，所属组也为 www。若显示为 root 或其他用户，点击「修改用户/组」进行修正。
3、在终端中执行 ls -l /www/wwwroot/your-site/dist/，逐行核对权限列与用户列输出是否符合预期。
