publicPath配置错误是H5白屏或404主因：部署根目录填/，子目录如/work/需严格匹配；双击打开需设./；history模式须配服务器fallback，否则刷新404；--dest只影响输出目录，不改变publicPath；跨端资源路径应统一用/static/绝对路径。
publicPath 配置错，页面白屏或资源 404
打包后打开 index.html 是空白页，或者控制台疯狂报 GET /static/js/app.js 404，八成是 publicPath 没配对。uni-app 的 H5 构建默认用绝对路径（/static/...），但你本地双击打开、或部署在子目录时，浏览器根本找不到这些资源。
- 若部署在域名根目录（如
https://my.com/），manifest.json的 H5 配置中填/ - 若部署在子目录（如
https://my.com/work/），必须填/work/—— 前后都要有斜杠，且必须和你最终上传的文件夹名完全一致 - 想本地直接双击打开（不走服务器），才需要在
manifest.json里加"publicPath": "./"；但注意：这会让所有资源引用变成相对路径，css里写url(./img.png)才有效，而src引图片得用require('./static/x.png')
history 路由模式启用后刷新 404
勾选了「开启 history 路由模式」，URL 看着干净了（/pages/index），但一刷新就 404 —— 这不是 uni-app 的 bug，是服务器没兜底。history 模式下，前端路由靠 JS 控制，但每次真实请求都会发到服务端，而服务端压根不知道 /pages/index 是个前端路由。
- Nginx 配置关键两行：
location / { try_files $uri $uri/ /index.html; } - Apache 需启用
mod_rewrite，加RewriteRule ^(.*)$ /index.html [L]到.htaccess - Vercel/Netlify 这类静态托管平台，需在项目根目录加
vercel.json或_redirects文件做 fallback - 不改服务器？那就别开 history，老实用 hash 模式（
/#/pages/index），它天然兼容所有环境
命令行打包输出目录和部署路径对不上
用 npm run build:h5 -- --dest h5-dist 打出的文件在 h5-dist/，但你在 manifest.json 里填的是 /app/，结果部署上去所有资源路径全错 —— 因为 publicPath 决定的是运行时资源加载路径，和打包输出目录无关，两者不能混为一谈。
-
--dest只控制生成文件放哪（如h5-dist），不影响线上 URL 结构 -
publicPath（即 manifest 中「运行的基础路径」）决定浏览器请求资源时拼的前缀，比如填/app/，那 JS 就会去请求/app/static/js/app.js - 上传时，把整个
h5-dist/文件夹内容，放到服务器的/app/目录下（Nginx root 或 alias 指向那里） - 常见错误：把
h5-dist整个文件夹传上去，然后用https://x.com/h5-dist/访问 —— 这样publicPath得填/h5-dist/，否则路径断层
静态资源路径在不同平台表现不一致
一张图，在 H5 上能显示，打包成小程序却黑屏 —— 很可能是路径写法太“H5 导向”。uni-app 编译器对各端资源解析逻辑不同，尤其是相对路径在 css 和 template 中行为差异大。
-
template中src引图片，推荐用require：<image :src="require('./static/logo.png')"></image>，这样各端都能正确解析 -
css中background-image不能用require，必须写相对路径；但 H5 用./logo.png，小程序可能要../../static/logo.png—— 更稳妥是统一用绝对路径/static/logo.png（前提是publicPath支持） - 避免在
static外放资源；所有静态文件进static/，引用时从/static/xxx开始写，减少跨端歧义
实际部署时最常卡住的，就是 publicPath、服务器 fallback、上传目录三者没对齐。三个地方名称不一致，哪怕只差一个斜杠，都会导致白屏或资源丢失。
