web-view src路径错误是真机404或白屏主因:Android需file:///android_asset/www/路径,iOS用__uniapp__/路径,H5须HTTP服务或v-html渲染;HTML须放static目录并引入uni.webview.js。

web-view src 路径写错导致真机 404 或白屏
绝大多数“加载失败”其实卡在路径上——web-view 不支持直接用 ./static/page.html 或 /static/page.html 这类相对路径,尤其在 Android 真机上会直接报 404,iOS 则可能静默白屏。
必须按平台区分处理:
- Android:用
file:///android_asset/www/static/page.html(注意三斜杠 +android_asset固定路径) - iOS:用
__uniapp__/static/page.html(双下划线开头,这是 uni-app 内置协议) - H5:不能直接加载本地 HTML,会跨域;必须走
uni.request拉取内容后用v-html渲染,或起本地 HTTP Server(如http-server)托管static目录
推荐用 #ifdef 条件编译动态赋值:src 绑定 data 中的变量,在 mounted 里根据 uni.getSystemInfoSync().platform 或预编译宏判断平台再拼路径,别硬写死。
HTML 文件没放对位置或没被正确打包
uni-app 只会把 static 目录下的文件原样拷贝进最终包,其他目录(比如 hybrid、assets)里的 HTML 默认不参与构建,真机运行时根本不存在。
立即学习“前端免费学习笔记(深入)”;
确认以下几点:
- HTML 文件必须放在
static目录下,例如static/local.html - 不要放在
pages、components或根目录,那些路径不会被打包进www目录 - 检查生成后的 App 包:Android 可解压
apk查看assets/www/static/是否存在该 HTML;iOS 可用 Xcode 打开.ipa的 Payload 查看www/static/
如果用了自定义目录(如 hybrid/html/),必须在 vue.config.js 里手动配置 copy 插件,否则构建时直接丢弃。
没引入 uni.webview.js 导致调不到 uni API
在本地 HTML 里想用 uni.navigateTo 或 uni.postMessage,光写代码没用——uni 对象根本不存在,因为 web-view 加载的是纯静态 HTML,不自动注入任何运行时。
必须手动引入官方 SDK:
- 在 HTML 的
里加:<script src="https://js.cdn.aliyun.dcloud.net.cn/dev/uni-app/uni.webview.1.5.2.js"></script> - 引入后需等
UniAppJSBridgeReady事件触发才能安全调用,否则uni是 undefined - 微信小程序环境还需额外引入
jweixin-1.4.0.js(仅需小程序通信时)
注意:这个 script 标签要写在你本地 HTML 文件里,不是写在 .vue 页面中;CDN 地址必须可访问,离线场景建议下载后放 static 下并用相对路径引用。
Android WebView 缓存策略让页面不更新
改了本地 HTML 内容,但真机上始终显示旧版?Android 系统 WebView 默认缓存行为是 LOAD_DEFAULT,它可能忽略本地文件变更,直接复用旧缓存甚至跳过读取。
必须在 web-view 加载完成回调里主动设置:
- 监听
@load或原生loaded事件 - 拿到
webview实例后立即调用:webView.setCacheMode("LOAD_CACHE_ELSE_NETWORK") - 该 API 仅 App 端有效,H5 端无效;且只对
file://协议生效
不设这个,哪怕你删了 HTML 文件,WebView 都可能从缓存里拉出一个已不存在的副本,表现为“页面还在,但内容没变”或者空白。
最易被忽略的是:路径协议和 SDK 引入必须同时正确,缺一不可。Android 上少写一个斜杠、iOS 少两个下划线、HTML 里忘了等 UniAppJSBridgeReady,都会导致看似加载成功实则功能瘫痪。



















