Taro4/Vite小程序页面样式丢失问题

在小程序开发中发现了一个样式故障。进入首页的某个A页面时，界面呈现为未加载任何 CSS 的原生骨架状态。字体尺寸、容器间距以及弹性布局全部失效。与之相对，首页同级的B页面采用近乎相同的列表布局，渲染结果却完全符合预期。

这两个页面由同一个开发团队在相近周期内完成。起初怀疑是页面模板缺少闭合标签，或是预编译语法错误打断了样式解析。比对业务组件结构与属性绑定后，源码层面并没有发现明显语法异常。

对于小程序平台的表现层异常，直接检查构建后的静态产物更有效一些。

查阅构建生成的 dist 目录可以直观的发现差异。在 dist/pages/grid-worker-group 下，index.js、index.json、index.wxml 与 index.wxss 结构完备。而在故障页面 dist/pages/partner-group 目录中，仅存在 index.js、index.json 和 index.wxml，对应的 index.wxss 文件完全缺失。

通过询问ai并查阅资料，微信小程序依靠页面路径同名的样式文件来注入独立作用域规则。构建产物中缺失了样式实体，运行时自然无法加载任何规则。排查方向由此收敛为，Taro 的构建流水线为何忽略了该页面的样式输出。

回溯样式的源码实现，两个页面的组织方式提供了线索。

partner-group/index.scss 声明了A页面列表所需的完整选择器与布局规则。而B页面的业务需求与A页面高度重合，为了减少重复代码，grid-worker-group/index.scss 仅包含一条导入语句。

@import '../partner-group/index.scss';

该页面未追加任何覆盖规则。经过 Sass 预处理后，两个页面输出的 CSS 抽象语法树与代码文本是完全一致的。

该项目运行在 Taro 4 环境，构建器配置为 Vite。在现代 Web 构建体系中，Rollup 与 Vite 会在生成静态资产时进行内容哈希比对。当多个入口模块引入完全相同的样式内容时，构建工具会将它们合并为同一个 CSS 资产，用以降低浏览器网络开销并提高缓存复用率。

然而小程序环境并不具备 Web 端动态挂载同一 CSS 的运行机制。微信小程序的架构要求每个页面必须持有自己同名的独立样式物理文件。

深入排查 @tarojs/vite-runner 的打包插件代码，在 dist/mini/style.js 中发现了关键逻辑。

该插件在 generateBundle 阶段遍历所有 Chunk，尝试将 Vite 生成的内部 CSS 文件映射为各页面专属的样式文件。

简化后的处理逻辑如下。

for (const name in bundle) {
  const chunk = bundle[name];
  const importedCss = chunk.viteMetadata?.importedCss;
  if (importedCss) {
    for (const item of importedCss) {
      const fileName = chunk.fileName.replace('.js', nativeStyleExt);
      bundle[item].fileName = fileName;
    }
  }
}

这段逻辑隐含了一个预设前提，即每个页面 Chunk 所依赖的 CSS 资产都是独占的。

当流水线处理到 partner-group 时，插件将共享的 CSS 资产路径指向了 pages/partner-group/index.wxss。但随后的循环继续处理到 grid-worker-group，由于B页面指向同一个被合并的内部资产，插件对该资产对象的 fileName 属性执行了二次赋值，将其改写为 pages/grid-worker-group/index.wxss。

由于被修改的是内存中的同一个引用，后一次赋值直接抹去了前一次的路径配置。当 Rollup 最终将内存资产刷写到磁盘时，只生成了最后一个页面的文件，前序页面的样式文件随之丢失。改名生效的顺序完全受制于 app.config.ts 中的页面声明顺序。

本来发现了bug，还想着混个PR，但在 Taro 官方仓库进行检索，该现象已被收录在 Issue #19485 中，标题为《不同页面有相同样式时不生成页面样式文件》。随后合入的 PR #19492 对此做出了修正。官方的修复策略是先统计每个 CSS 资产关联的所有目标页面，保留一份初始资产后，利用插件上下文的 emitFile 为其余页面生成独立的同源产物。该修正包含在后续的 4.3.0 版本中。

当前项目基于 Taro 4.2.0。针对生产环境的修复，通常面临版本升级与工程规避的选择。

升级基础框架次版本虽然能获得上游修复，但在跨端项目中，全量升级往往伴随着构建插件、运行时桥接，引入未经验证的回归风险。在项目交付阶段，选择在业务层打破触发条件的代价要低得多。

既然问题源于样式文本完全一致触发了 Vite 的去重策略，只需在B页面声明独有规则，使两者的 AST 产生差异即可。

在 src/pages/grid-worker-group/index.scss 中补充页面专有类名。

@import '../partner-group/index.scss';

.grid-worker-group-page {
  display: block;
}

再次执行构建，Vite 判定样式内容不同，为两个页面分别分发了独立的内部 CSS 资产。构建日志显示两者被分配为不同文件名，dist 目录中均成功生成了对应的样式文件，页面渲染随即恢复正常。

这次排查也带来了一些关于辅助研发的思考。

如果遇到样式失效的第一时间，直接把页面白屏或错位的截图发给大模型提问，往往会得到一长串通用的排查建议，例如检查弹性盒模型、审查父级容器定位或者排查类名权重。

这些建议看似很合理，却无法触及实际原因，因为业务源码本身没有错，错在构建环节缺失了文件。

目前的LLM擅长在给定的上下文中进行模式推演，但它无法直接读取本地运行时的物理状态。把界面表象当做问题原点向工具求助，容易在错位的方向上反复修补源码。所以还是要提高自身排查问题的能力。