生产环境白屏是资源加载、脚本执行或渲染环节断开所致：1.检查vite与Vue Router的base配置是否匹配部署路径；2.添加@vitejs/plugin-legacy兼容低版本浏览器；3.禁用file://直接打开dist，须通过HTTP服务访问。
生产环境白屏不是单一问题，而是多个常见原因叠加的结果。核心要分清：是资源没加载、脚本执行失败，还是页面渲染卡住。下面从最常发生的三类情况出发，给出可落地的解决路径。
检查构建 base 路径是否匹配部署位置
Vue Router 或静态资源路径错位，会导致 JS/CSS 404，页面空有 HTML 框架但无内容。尤其当项目部署在子路径（如 /admin/）时，必须显式配置 base。
- 在 vite.config.ts 中设置
base: '/admin/'（上线路径以斜杠结尾） - 同时确保 Vue Router 的
createRouter配置中base与之完全一致 - 打包后检查 dist/index.html 中 script 和 link 标签的 src/href 是否都带了
/admin/前缀
修复低版本浏览器语法兼容性报错
控制台出现 Unexpected token '...'、'?'、'.' 或 'const'，基本锁定为 ES2015+ 语法未转译。Vite 默认只兼容较新浏览器（Chrome ≥87），老设备或 WebView 会直接中断执行。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 安装兼容插件：
npm i @vitejs/plugin-legacy -D - 在 vite.config.ts 的 plugins 中加入：
legacy({ targets: ['chrome 52', 'ie >= 11'] }) - 补充 polyfill（如需支持 IE11）：
additionalLegacyPolyfills: ['regenerator-runtime/runtime'] - 确认打包产物中生成了
index-legacy.js和对应入口逻辑
避免本地双击打开 dist/index.html 导致的 CORS 报错
用 file:// 协议直接打开 index.html 时，浏览器禁止模块化脚本跨文件加载，控制台会报 “Access to script at 'file://...' has been blocked by CORS policy”，页面必然空白。
- 这不是代码缺陷，而是浏览器安全限制，生产环境不应依赖 file:// 访问
- 正确做法：用 HTTP 服务启动 dist 目录，例如
npx serve -s dist或配置 Nginx - 若必须本地验证，可在 vite.config.ts 中加
build.rollupOptions.output.manualChunks降级为 IIFE 格式，并移除type="module"，但仅作临时调试
白屏问题本质是前端加载链路中的某个环节断开。先看控制台第一条错误，再顺着 HTML → JS 加载 → 脚本执行 → 路由匹配 → 组件渲染逐层验证，比盲目改配置更高效。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
