HTML文档本地资源在混合开发模式下的重定向映射实战

鸿蒙 WebView 中 rawfile 资源路径 404 的根本原因是其扁平化挂载机制与 WebView 相对路径解析逻辑不匹配，必须在 loadFile 前调用 setBasePath("resources/base/rawfile/") 才能正确解析资源路径。

鸿蒙 WebView 中 rawfile 资源路径为何 404？

鸿蒙 WebView 加载本地 HTML 时，src 或 href 指向 ./css/main.css、../js/book.js 却报 404，根本原因不是文件不存在，而是鸿蒙的 rawfile 目录结构和 WebView 的资源解析机制不匹配。鸿蒙将所有 rawfile 文件扁平化挂载到 resources/base/rawfile/ 下，但 WebView 默认以 HTML 文件所在路径为基准解析相对路径——而 HTML 文件本身是通过 webview.loadFile("index.html") 加载的，它没有“所在目录”概念，导致所有相对路径全部失效。

• 必须显式设置 WebView 的基础路径：调用 webview.setBasePath("resources/base/rawfile/")（注意末尾斜杠）
• <base href="."> 在鸿蒙 WebView 中基本无效，尤其当 HTML 由 loadFile 加载时，浏览器会忽略它
• 绝对路径写法 /css/main.css 也不行——鸿蒙不支持根路径映射到 rawfile，只认相对路径 + setBasePath
• 验证是否生效：在 DevTools Network 面板中看请求 URL 是否变成 resources/base/rawfile/css/main.css

如何让 index.html 正确加载同级的 assets 目录？

你把 index.html、assets/css/、assets/js/ 全部放进 resources/base/rawfile/，但默认加载后 CSS 仍 404。这不是路径写错，而是鸿蒙对子目录的处理有隐含规则：它不会自动识别并挂载子目录为可访问路径，必须靠 setBasePath + 统一前缀来“欺骗”解析逻辑。

• 把整个资源树重组织：将 assets/ 内容直接提到 rawfile/ 根下，即 rawfile/main.css、rawfile/book.js
• 或保持目录结构，但 HTML 中全部改用带前缀的相对路径：href="assets/css/main.css"，同时确保 setBasePath 指向 resources/base/rawfile/
• 切勿用 file:// 协议拼接路径——鸿蒙 WebView 不支持该协议访问 rawfile 资源
• 注意大小写：鸿蒙设备（尤其是真机）对文件名大小写敏感，Main.css 和 main.css 是两个文件

JavaScript 动态加载资源时路径怎么写才可靠？

用 fetch("./data/chapter1.json") 或 new Image().src = "./img/cover.png" 在鸿蒙 WebView 中极易失败，因为这些 API 不受 setBasePath 影响，它们严格按当前文档 URL 解析相对路径——而文档 URL 是 about:blank 或空字符串。

• 统一用绝对路径字符串拼接：fetch("resources/base/rawfile/data/chapter1.json")
• 或者封装一个路径生成函数：function res(path) { return "resources/base/rawfile/" + path; }，然后 fetch(res("data/chapter1.json"))
• 避免使用 import 加载本地模块——鸿蒙 WebView 当前版本（API 12）不支持 ES Module 的本地文件导入
• 动态 script 标签注入时，src 必须是完整路径，且需确保脚本执行时机在 DOM 加载完成后

为什么 Nginx 的 rewrite 规则在鸿蒙本地开发中完全不适用？

你在服务器上用 rewrite ^(.*).html$ .php last; 实现伪静态，迁移到鸿蒙后试图复用同一套 HTML+JS，却发现所有 .html 请求根本没经过任何服务端，自然 rewrite 失效。鸿蒙 WebView 是纯客户端加载，没有 HTTP 服务器参与，所有路径解析都在前端完成。

立即学习“前端免费学习笔记（深入）”；

• 本地混合开发中，“URL 重写”只能靠前端逻辑模拟：比如监听 webview.onUrlLoad，拦截 /book/123.html 这类路径，再用 webview.loadFile("book.html?chapter=123") 重新加载
• 不要在 HTML 里写 location.href = "/book/123.html" 并指望它被映射——它只会触发 404
• 如果必须保留路由语义，建议用 history.pushState + 前端 router 库（如 Page.js），配合 webview.setJavaScriptInterface 暴露原生跳转能力
• 真正的服务端重定向（301/302）只在你 WebView 加载远程 URL 时起作用，对 loadFile 无意义

最易被忽略的一点：鸿蒙 WebView 的 setBasePath 必须在 loadFile 之前调用，且不可重复设置；一旦页面开始加载，再改 base path 就无效了。很多团队卡在这一步数小时，只因把 setBasePath 放在了 onPageStarted 回调里。