Vue项目打包后本地打开index.html白屏，根本原因是file://协议下浏览器无法正确加载绝对路径资源且不支持history路由；需将publicPath设为'./'并改用hash路由或本地服务器运行。
打包后HTML文件打开空白或报错，先确认是否在本地直接双击运行
很多前端同学打包完 index.html 直接双击打开，结果白屏、控制台报 net::ERR_FILE_PROTOCOL 或资源 404。这是因为现代打包工具（如 Vite、Webpack）默认生成的资源路径是相对路径或带哈希的，而 file:// 协议下浏览器会禁用跨域请求、无法解析 import 语句、也不能正确加载 assets/xxx.js 这类相对路径资源。
实操建议：
- 用轻量 HTTP 服务本地预览：比如
npx serve -s dist（需全局装serve），或python3 -m http.server 8000（Python 自带） - 检查打包输出的
dist/index.html中 script 标签的src是否为相对路径（如./assets/index.xxxx.js）——这是正常行为；但若看到src="/assets/xxx.js"（开头是斜杠），说明base配置可能设成了'/'，部署到子路径时就会 404 - Vite 用户重点看
vite.config.ts中的base字段：开发用'/'没问题，但部署到https://example.com/my-app/就必须设成'/my-app/'
控制台报 “Failed to load module script” 或 “Unexpected token ‘
这是最典型的 HTML 被当 JS 执行的错误。本质是服务器把 index.html 返回给了本该请求 JS 的 URL，比如浏览器请求 /assets/index.abc123.js，但 Nginx 或 GitHub Pages 返回了 index.html 内容（HTML 开头是 /code>），JS 解析器一读就报 Unexpected token '。
实操建议：
- 打开浏览器开发者工具 → Network 标签页 → 刷新页面 → 找红色的 JS/CSS 请求 → 点开它 → 看 Response 内容是不是 HTML 源码而不是 JS 代码
- 如果是，说明静态服务器没配好 fallback：Vite 打包产物需要支持“SPA fallback”，即所有非资源请求都返回
index.html；但资源请求（带.js、.css、.png后缀）必须真实返回对应文件 - Nginx 示例配置中必须包含
try_files $uri $uri/ /index.html;，且放在location /块里；不能写成try_files $uri /index.html;（漏了$uri/会导致目录访问失败）
打包后样式丢失、图片不显示，检查 public 目录和路径引用方式
很多人把图片、字体、favicon.ico 放进 public/ 目录，以为能直接用 /logo.png 引用，结果部署后 404。根本原因是：Vite/Webpack 对 public/ 下文件不做 hash 和重命名，但对 src/ 下的资源会走构建流程，路径处理逻辑完全不同。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
实操建议：
-
public/下的文件，引用时路径必须以/开头（如
/是相对于站点根目录的——如果部署在子路径，就要手动补前缀，或者改用import方式引入 - 更稳妥的做法：把图片等资源放进
src/assets/，用import logo from '@/assets/logo.png'，然后 - 检查
dist/目录里是否真有那个文件：比如你写了src="img/icon.svg"，但实际文件在src/assets/img/icon.svg，构建后路径可能是assets/icon.xxxx.svg，硬编码的img/icon.svg就必然 404
Source map 失效导致无法调试打包后的 JS
打包后 JS 是压缩混淆过的，Chrome DevTools 里断点打不上、调用栈全是 webpack:// 或 vite:// 协议，点不开源码——这不是 bug，是 source map 没生效或没生成。
实操建议：
- 确认构建时开启了 source map：Vite 用户检查
build.sourcemap是否为true（默认false）；Webpack 用户检查devtool是否设为'source-map'或'cheap-module-source-map' - 生成后检查
dist/assets/*.js.map文件是否存在，以及对应 JS 文件末尾是否有//# sourceMappingURL=xxx.js.map注释行 - Chrome 中打开 Settings → Preferences → Sources → 勾选 “Enable JavaScript source maps” 和 “Enable CSS source maps”；再刷新，就能在 Sources 面板看到原始
src/文件结构 - 注意：生产环境一般不发布 .map 文件，调试时可临时开启，但上线前务必关掉或移除
.map文件，避免暴露源码结构
真正卡住人的往往不是某个报错，而是多个路径配置（base、publicDir、服务器 root、反向代理 rewrite 规则）之间互相影响，改一处可能引发另一处失效。建议每次只动一个变量，用 Network 面板盯死具体哪个请求挂了、返回了什么内容，比猜更可靠。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
