WebView 与本地 H5：改在 assets 还是 res/raw，白屏怎么排查

还是先介绍主角。安卓修改大师智改工坊是一款 Windows 桌面工具：把安装包拖进去，用中文写下需求，AI 在反编译出来的工程里改代码与资源，改完自动回编、对齐、签名、校验，最后一键装到手机或模拟器上拉起来看效果。它的介绍页在 https://www.apkeditor.cn/ai-version.aspx，官网是 www.apkeditor.cn。

这篇要聊的是应用里那些"网页"。很多安卓应用都内嵌了 WebView：活动页、帮助页、用户协议、数据报表、运营专题 —— 它们看起来是"应用内的一张网页"，实现的差别却可能是三种完全不同的形态。这个差别直接影响你能不能改、怎么改：网页文件在包里的时候，改包就能改页面；网页只存在于服务器上的时候，改包只能改"应用去访问哪个地址"。 这是本章第一条、也是最重要的一条边界。

第二条边界来自一个非常恼人的现象：改完了，页面是白的。 空白页是 WebView 改造里出现频率最高的故障，而它的原因基本上落在三类里 —— 缓存还在用旧的、路径对不上、编码不对。三类都不难处理，难的是"不知道往哪儿看"。所以这篇会把这三类拆开讲透，再补上一份"缓存在哪、什么时候该清"的清单，最后讲最有意思的一段：怎么把"这个页面对应哪个文件"这种只有你知道、AI 不可能知道的信息，用附件机制准确地传过去。

一、应用里的网页从哪儿来：三种来源，先分辨再动手

从开发的角度看，WebView 显示的内容无非是"一个地址"。但这个地址有三种性质完全不同的写法，落到改包上就是三条不同的路：

来源	典型地址写法	文件在不在包里	改包能改什么
assets 本地页面	file:///android_asset/网页路径	在，且原样保留	页面内容、图片、样式、脚本全能改
res/raw 资源	读成一个资源再喂给 WebView	在，但会被编译进资源表	单个文件可换，路径与名字不能随便动
远程 URL	https://域名/路径	不在，包里只有地址	只能改"访问哪个地址"，页面本体在服务器上
混合	本地页面里再请求远端数据	壳在包里，内容不一定	改壳能看到版式变化，但文字可能是服务器给的

怎么分辨属于哪一种？在工程里做两件事就够了。第一，搜关键字：搜 android_asset、loadUrl、loadDataWithBaseURL 这类痕迹，看它最后把哪个地址交给了 WebView；第二，看 assets 目录有没有对应的页面文件 —— 有 html、css、js、图片的目录结构，基本可以认定是本地页面。

这些问题的共同根源不是"没写代码"，而是没有先把关系定死：谁是页面、谁是数据、谁只是壳，混在一起之后，任何一个动作都会同时改变好几样东西。

另外还有一层现实意义：这四种来源对应的"验收方式"也不一样。本地页面改完，靠冷启动看效果就行；远程地址改完，得看打开的是不是新站点（断网时会打不开，属于正常现象）；混合型的页面，改完本地壳只能改变版式，文字内容仍取决于服务端返回。先分清来源，你就同时确定了"改什么"和"怎么验收" —— 这也是为什么我们把"分辨来源"放在整篇文章的第一步。

混合型最容易让人误判，值得单独说一句：本地页面里的文字，很可能是页面加载后用脚本从服务器取回来的。于是你改完了本地的 html，却发现页面上那些字一个都没变 —— 因为你改的是"壳"，内容在服务端。遇到"改了没反应"的页面，第一步不是怀疑工具，而是先确认这段内容到底存在哪儿：把那个 html 在电脑浏览器里打开看一眼，页面里是写死的文字还是空的容器，一眼就能分辨。

二、本地 H5 改在 assets 还是 res/raw：不只是"放哪儿"的问题

确认页面文件在包里之后，第二个问题就是它现在放在哪儿 —— 因为这决定了替换时要遵守什么规矩。两个目录的差别，用一句话概括：assets 是"原样带走的行李"，res/raw 是"编进册子的档案"。行李可以保持原来的目录结构与文件名，档案则要被登记、编号、按规矩命名。

对比项	assets 目录	res/raw 目录
怎么被引用	按相对路径（配合 android_asset 前缀）	按资源名（代码里的 R.raw.名字）
能不能有子目录	可以，整站目录随便摆	不能，只能平铺单层
文件名的限制	几乎没有，任意扩展名与大小写	只能小写字母、数字、下划线；带大写或连字符会在编译阶段直接报错
适合放什么	整站 H5（html + css + js + 图片 + 字体）	单个文件，例如一份静态页、一份模板
替换时的规矩	保持目录结构与文件名，相对引用不用动	保持资源名不变，改名就要同时改引用它的代码

表面上看，assets 更自由，但"自由"的另一面是它把"引用关系"藏在了文件内容里：本地页面里的 css、js、图片通常是相对路径引用（比如 ./css/style.css、../img/logo.png）。这意味着只要你把页面文件放到别的位置、或者改了某一层目录名，那些相对引用就会全部失效 —— 页面本身还在，但样式和图片全丢，看起来就像"坏掉的白板"。所以本地 H5 的第一条铁律是：替换时保持原目录结构不变，尤其是文件名的大小写，一个字母都不要改。

反过来，改路径这件事在工程上是可行的，只是成本完全不同：保持原路径替换文件，改动量是零（没有任何引用需要调整）；改名或改目录，就得把"谁引用了它"全部找出来一起改 —— 页面的相对引用在 html/css 里、路径常量在代码里，而且通常是字符串拼接起来的，搜都不一定搜得全。所以如果你确实想把页面挪个位置（比如统一到新的目录结构），更稳的做法是分两步走：第一步只替换内容、验证效果；确认没问题后，第二步再单独做"搬家"，这样出问题你能立刻知道是哪一步引入的。

顺便提醒一类容易被忽略的资源：页面里用到的字体文件与图标字体。它们通常和 css 放在一起，被样式表引用，平时不显眼，但一旦替换页面时"顺手"换了 css 却忘了同步字体文件，页面上的图标就会变成一个个小方块 —— 观感上像是"页面坏了"，实际只是少了一个资源。处理原则和前面完全一致：名字与路径都不要动，只换内容；如果这次确实要换字体（换了字体，字号与行高往往也要跟着调），那就把它当成一次"页面改版"整体处理，而不是当成一次"替换文件"。把"替换"和"改版"分开做，是这套流程里最能减少返工的一条纪律。

三、改完为什么页面空白：三类原因与一份排查顺序

前面说空白页的原因落在三类里，这里逐一拆开。每一类都会给出"怎么确认"和"怎么处理"，你可以在装完包、看到白屏的那一刻按顺序往下走。

第一类：缓存 —— 你看到的是旧的那一份

WebView 是个"会记东西"的浏览器：它会把加载过的页面与资源缓存起来，下次优先用缓存，以求打开更快。这个机制在正常使用时是优点，在你改包验证时就是敌人 —— 页面没坏，只是显示的还是上一版。此外还有一种更隐蔽的情况：资源被替换后，页面旧版本里引用的某个文件已经不存在了（比如旧 html 引用 promo-v1.jpg，新版本里只有 promo-v2.jpg），于是脚本报错、页面停在空白 —— 表现和"缓存问题"一模一样，但根源是路径。

确认与处理：先做一次"排除法"—— 把页面对应从冷启动开始看一遍（彻底退出应用再打开，别从后台切回来）；如果还是旧内容，就去清一次应用缓存（下一章会给具体位置），再冷启动；两次做完还是旧内容，那基本不是缓存，往下走查路径。另外一个很实用的判断技巧：如果页面显示的是"旧版内容 + 新版样式"这种混合状态，几乎可以断定是缓存与替换各占一半，清缓存即可解决。

第二类：路径 —— 文件在，但没人能找到它

路径问题的表现形式比缓存更"像坏了"：整页白、样式全丢、图片全碎。前面提过的大小写问题是最常见的成因，其次是三种：第一，页面被换到了别的目录，但代码里写的还是旧路径；第二，页面内部的相对引用因为目录层级变化而失效（把 www/index.html 挪到了 h5/index.html，页面里所有 ./css/ 就都指错了）；第三，本地资源与 raw 资源的地址前缀搞混了 —— 包内文件用的是"安卓资源"那一套地址前缀，把文件从 assets 挪到 raw（或者反过来）而不改地址，必然打不开。

确认与处理：在电脑上把新页面的目录结构原样打开一遍，逐个点开页面里引用的每一个 css、js、图片，看是否都存在、名字是否完全一致（逐字节比较文件名，而不是"看起来一样"）；然后把这份目录结构与工程里的实际结构对照一遍。这一步花十分钟，能省掉反复装包的几十分钟。

第三类：编码 —— 页面能打开，但中文是乱码，或者干脆解析失败

编码问题有两种表现：一种是文字变成一串看不懂的符号；另一种更严重 —— 页面头部声明的编码与实际保存的编码不一致，浏览器在解析时把标签解析错了，整个页面结构直接崩掉，看起来就是一块白板。正确的姿势只有一句话：让"文件实际的编码"和"页面里声明的编码"统一。如果页面里写的是 UTF-8（绝大多数情况），那么保存文件时也必须是 UTF-8，不要用 GBK、ANSI 这些本地默认编码去覆盖；反过来如果原页面声明的是别的编码，就跟着它走，不要擅自改声明。

还有一个细节值得提一句：用某些 Windows 编辑器保存 UTF-8 时会默认加上一段看不见的标记（俗称 BOM）。它在多数情况下无害，但在个别解析路径上会让页面的开头多出几个"看不见的字符"，进而影响页面头部的解析。如果页面只坏在开头一小段（比如标题栏跑出奇怪符号），优先怀疑这个。 处理方式也很简单：把这个页面另存为"不带标记的 UTF-8"再替换一遍。

把这三类原因和它们对应的"第一步动作"整理成一张速查表，装机后看到异常时对着找，比漫无目的地点来点去快得多：

你看到的现象	最可能的原因	第一件该做的事
整页空白，什么也没有	路径找不到页面文件，或文件没被打进包	核对文件是否在工程内、路径与大小写是否一致
显示的还是上一版内容	缓存优先	冷启动 + 清一次应用缓存，再打开一次
页面有内容，但样式全丢、图片全碎	相对引用失效（目录层级或大小写）	逐个核对页面引用的每个 css / 图片路径
中文乱码，或页面开头出现怪符号	编码不一致，或保存时带了多余标记	把文件另存为与页面声明一致的编码再替换
本地改完没变化，断网后也正常	改的可能不是真正在用的那份文件	确认有没有同名文件在别的目录里被优先加载
断网后就打不开了	它是远程页面，或本地页依赖远端资源	确认来源类型，改包能改的只有本地那一部分

四、WebView 的缓存在哪，什么时候该清

把缓存单独拿出来讲，是因为它有一个反直觉的性质：它跟着"应用的数据"走，不跟着"安装包"走。这带来两个后果。第一，你用覆盖安装的方式装上新包，旧缓存还在原地 —— 改完看不到变化是正常的。第二，如果真的要看"新包的干净效果"，最可靠的对照实验是卸载旧包再装新包（这会把它的数据与缓存一起清掉）。当然，卸载有代价（会清掉应用里的本地数据），所以更常用的做法是只清缓存、不动数据。

清除的动作有三个层次，从轻到重：

• 系统设置里清"缓存"：在设备的应用管理里找到该应用，选择清除缓存（注意别点成"清除数据"—— 那会把登录状态、本地设置一起清掉）。这一档最常用，能解决绝大多数"页面还是旧的"。
• 清"数据"：连应用自己的存储一起清掉。适合那种把页面资源缓存在应用私有目录、而且缓存策略很激进的应用。清完通常要重新登录一次。
• 卸载重装：最彻底，也最干净。注意如果新旧包的签名不同，覆盖安装本来就会失败，此时必须先卸载 —— 工具遇到这种情况会明确提示你先卸掉再装，而不是让你在"装不上"里猜原因。

什么时候该清？记住三个时机就够了：改完页面第一次验证前（避免被旧缓存误导）、连续替换了同一批文件的多个版本之间（每一版之间清一次，才知道看到的是哪一版）、给同事复现问题时（让对方从"卸载后重装"开始，避免你们看到的根本不是同一个状态）。这三个时机之外，不需要频繁清 —— 缓存本身是个好东西。

这里还有一个很多同学关心的实际问题：能不能先在电脑上把页面调好、再替换进包里？ 可以，而且这是推荐的顺序 —— 页面的版式、文案、图片，先在电脑浏览器里改到满意，再作为附件交给工具替换。但要记住"电脑上正常"不等于"手机上也正常"：手机上的网页视图与电脑浏览器并不完全一样，脚本能力、字体可用性、以及本地文件之间的相互访问限制都不同。所以"电脑上过了"只意味着页面本身没写错，最终的验收仍然要在设备上做 —— 装包、冷启动、点进那个入口看一眼，这三步一个都不能省。

顺着这个思路，有一个小习惯很值得养成：替换之前先把"页面在电脑上打开的样子"留一张截图，装机之后再截一张。两张图摆在一起对比，你立刻能分辨出"是我的页面本来就这样"还是"打进包里之后坏了" —— 这个对照动作能在几秒钟内把排查范围缩小一半，比任何猜测都有效。

五、附件机制：把"页面对应哪个文件"说清楚

现在到了本篇最实用的一段。前面所有分析都指向同一个前提：你得先知道要改的文件在哪儿。 而这件事，往往是"只有你知道"的 —— 因为它是你们自己应用的结构习惯，AI 再聪明也猜不出来。工具的附件机制就是为了把这个信息顺畅地交出去而设计的。

它的工作方式是这样的：点「选择附件」可以一次挑多个文件，并且要给每个文件写一句"它是干什么用的"。确认时会做两类检查：一类是这个文件现在能不能用（文件存在、不是目录、不是 0 字节、能读出来 —— 被别的程序独占锁住的文件也算不可用，因为发过去 AI 也读不到）；另一类是那句用途说明不少于 10 个字。此外，同一个路径被重复选中时不会新增一行，而是自动去重 —— 因为同一份文件带着两条说明发过去，AI 反而不知道该听哪一条。校验通过之后，附件会拼成一段形如「序号. 文件路径 —— 用途说明」的清单，跟在你的需求后面一起发出去，并且会明确告诉 AI：这些文件已经放在磁盘上，需要放进应用的，由它自己决定放到工程里的哪个位置。

注意最后半句 —— "由它自己决定放到工程里的哪个位置"，就是为什么你的说明必须写到"目标路径"这一层。 只写"这个是新的首页"，AI 得猜放哪儿；写"替换本地页面目录下的首页文件，页面里的 css/js 相对路径保持不变"，它就有了明确的落点。这个差别，几乎等于"一次成功"与"来回三次"的差别。

前面那一组校验看起来啰嗦，实际每次都可能在替你挡一次事故。举个最日常的例子：你刚在某个编辑器或压缩包里打开过那张图，文件被程序独占锁着 —— 你自己看不出来，但发过去的路径 AI 读不到，于是它"以为"没有附件，照着需求硬改，最后产出和你预期完全不同的东西。四项检查（文件在不在、是不是目录、是不是 0 字节、现在读不读得出来）加上"说明不少于 10 个字"，本质上都是同一件事：把所有"只能靠猜"的环节，提前变成"必须说清楚"的环节。

说明写法	问题	结果
"新首页"	没说替换谁、没说文件自身是什么	AI 只能猜，多半会放错位置
"替换 assets 里那个首页 html，注意保持相对路径"	说了目标，但没给完整的文件结构信息	基本可用，遇到多入口页面时还可能选错
"替换应用本地页面目录里的首页文件（原文件是 help.html），文件名与所在目录保持不变；页面里的 css/js/图片都是相对路径引用，请一并核对是否都能找到；页面顶部 banner 图单独见另一个附件"	偏长，但每个字都有用	一次命中的概率最高，出问题也好定位

还有一个机制上的细节，直接关系到"复用"这件事：修改历史里只记你自己写的原话，附件与它们的说明不会进历史 —— 这是有意为之的（历史列表要干净，不能被一长串路径刷屏）。所以当你从历史里点「选择」把上次的需求填回输入框、准备"照上次那条再改一遍"时，记得重新把附件选上。这个提醒看起来小，但它是"复用旧需求"时最容易漏的一步。

这段模板里有三个值得学的写法：一是给每个附件都点了名（附件 1 / 附件 2），让说明和文件一一对应；二是明确"引用路径不要改"，把最容易出问题的那一步先锁住；三是明确"不要动别的页面与目录结构"，把改动范围框死。 需求写得越像一份小工单，改出来的东西就越接近成品 —— 这是我们在多种改造里反复验证过的一条经验。

六、两个自家改包实例：从"翻半天"到"一次说清"

下面两个例子都是我们与身边同事的日常：改的是自家与内部应用、自有素材。重点看"以前怎么做 / 现在一句话怎么做 / 改完怎么验证"。

实例一：给内部「巡检打卡」工具换掉内置帮助页。

这是公司内部给巡检同事用的工具应用，"帮助"入口点进去是一个内置的网页 —— 本地页面存在包里，内容是一份巡检流程说明与常见问题。这次换版要把整页文案换成新一版，同时把页面顶部的横幅图换成新的。以前的做法：反编译之后先在包里翻出页面文件（这一步最烦，因为页面可能藏在几层目录里，而且"帮助页"的目录名未必有帮助字样），改完 html 之后还要专门检查它引用的样式与图片路径有没有被破坏；然后是回编、签名、装机、点进帮助页看效果。最常翻车的一步是"装机打开还是旧内容"：同事以为没改成，其实是应用缓存了旧页面，折腾一轮才发现清一下缓存就好了。

现在一句话：把自家的包拖进安卓修改大师智改工坊，需求写"把应用内置的帮助页换成附件 1 的页面文件：文件名与所在目录保持不变，页面里的 css/js 与图片都是相对路径引用，请核对引用都能找到；页面顶部横幅换成附件 2 的图，引用路径不要改；不要动别的页面与目录结构"，把两个文件作为附件加进去，并给每个附件写清用途（用途说明要求不少于 10 个字，正是为了逼出"这份文件到底替换谁"这个信息）。点「立刻修改」之后，AI 改完在项目目录留下标志文件，主窗口每 2 秒轮询一次，读到就自动弹出打包窗口；打包走回编、对齐、签名、校验四步，产物落在项目的 build 目录里。

改完怎么验证？在打包窗口勾上"打包后自动运行"：程序会用 adb 找到手机或模拟器，把包装上并拉起（手机走投屏、模拟器把窗口提到最前面），再用系统查询复核一次前台应用确实是它 —— 因为内置页面一眼就能看出新旧，关键是别被缓存骗了：如果打开还是旧内容，先彻底退出应用再冷启动一次，还不对就去系统设置里清一次该应用的缓存，再看。三次对照下来，你就能确定看到的到底是新包还是缓存。

实例二：给自家「记账助手」的"关于"页换版式，并把一个远程地址换掉。

这个应用里有两个网页形态的入口：一个"关于我们"是本地的页面（写在包里），另一个"服务条款"则是打开一个远程地址。这次两件事一起做：关于页换一版排版（换了新的配色与字体），服务条款那一项要从旧域名换到公司新的站点域名。以前的做法要分两条路走：本地页面这条，改文件；远程地址这条，得在工程里搜出那个地址（它可能写在资源里，也可能拼在代码里），换掉之后再回编签名 —— 而最容易出错的是地址写错一个字符，装机之后打开是"打不开的网页"，看起来和"页面白屏"一模一样，排查方向却完全不同。

现在的做法干脆把两件事写进同一条需求："把'关于我们'页面换成附件 1（保持文件名与目录不变）；同时把'服务条款'打开的地址改成新的域名地址，改完把这个地址在工程里替我搜一遍，确认旧地址没有残留。"——注意最后半句：让 AI 在改完之后做一次自查。这是附件机制之外的另一个好习惯：把"验收动作"也写进需求，你拿到的就多一次交叉确认。

验证的方式同样区分两条：本地页面那条，冷启动 + 清缓存对照；远程地址那条，装机后点开"服务条款"，看是不是新站点，同时断网测一次——远程网页在断网时本来就打不开，这是正常的；但如果本地页面在断网时也白屏，那说明它有依赖远端资源的成分，需要往"混合型"那个方向重新确认一遍。这个"断网对照"的小实验，能帮你快速分清"这个页面到底靠不靠自己"。

七、用户评价：他们改内置页面时的经验

下面几位的说法来自内部试用与交流群的整理，谈的是各自的用法和体会：

八、结语：先分清来源，再说清目标，最后用清缓存对照验收

把这篇收成三句话：先分清网页的来源（包内 assets、raw 资源、远程地址、还是混合），这决定了改包能不能改到页面；再用附件把"哪个文件替换哪个位置"说到路径这一层，因为这件事只有你知道；最后用"冷启动 + 清缓存"的对照来验收，别让缓存替你下结论。 三句话里没有一句是玄学，全部都是可以在十分钟内执行的检查项。

于是你打开安卓修改大师智改工坊时的体验，就是那句口号描述的样子：只需说话，就能让应用变成你想要的样子 —— 拖入自家安装包，把页面文件与图片作为附件、写好用途，用中文说清替换目标与保留要求，AI 改完自动回编、对齐、签名、校验，再一键装到设备上拉起来核对。内置页面这种"看起来零碎、实际很有讲究"的改造，从此也只是一份工单。

产品介绍页与下载入口：https://www.apkeditor.cn/ai-version.aspx（官网 www.apkeditor.cn）。