UniApp分包中静态资源访问问题的解决方案

问题背景

在UniApp开发中，当项目采用分包结构时，开发者可能会遇到静态资源访问路径的问题。特别是在H5端和小程序端表现不一致的情况下，这给开发者带来了困扰。

典型问题场景

假设我们有一个UniApp项目，目录结构如下：

src
├─packages
│  ├─pkg-a
│  │  ├─static
│  │  │  ├─image.png
├─pages

在分包配置中，我们将pkg-a配置为一个分包：

{
  "subPackages": [{
    "root": "packages/pkg-a",
    "pages": [...]
  }]
}

当我们在页面中使用<image>组件引用这个图片时：

<image src="/packages/pkg-a/static/image.png"></image>

问题表现

1. 微信小程序端：在开发和生产环境下都能正常访问
2. H5端：
   • 开发模式下找不到文件
   • 生产构建时会报错：Rollup failed to resolve import...

根本原因分析

这个问题源于Vite构建工具在处理静态资源路径时的机制。UniApp在Vite模式下，对于分包中的静态资源路径解析需要特殊处理。

解决方案

基础解决方案

最简单的解决方案是在路径前添加@符号：

<image src="@/packages/pkg-a/static/image.png"></image>

这个@符号会被UniApp/Vite正确解析为项目根目录。

自定义组件中的路径处理

当我们在自定义组件中使用图片路径时，需要额外配置。例如：

<!-- AppImage.vue -->
<template>
  <image :src="props.src"></image>
</template>

在页面中使用这个组件：

<app-image src="@/packages/pkg-a/static/image.png"></app-image>

为了使这种用法正常工作，需要在Vite配置中添加特殊处理：

const assetURLTagConfig = {
  tags: {
    'app-image': ['src'],
    // 可以添加其他自定义组件
  },
}

// 在uni插件配置中添加
uni({
  vueOptions: {
    template: {
      transformAssetUrls: assetURLTagConfig,
    }
  }
})

版本兼容性说明

从UniApp 3.0.0-alpha-4020120240617001版本开始，微信小程序端也会出现类似的路径解析问题。因此，建议所有项目都采用上述解决方案，以确保跨平台兼容性。

最佳实践建议

1. 对于分包中的静态资源，始终使用@前缀的路径格式
2. 当创建使用资源路径的自定义组件时，记得在Vite配置中注册组件名和属性
3. 在项目早期就建立统一的资源引用规范，避免后期修改成本

通过遵循这些实践，可以确保UniApp项目在不同平台和构建模式下都能正确加载分包中的静态资源。