#代码包体积优化

代码包体积直接影响小程序的下载耗时。体积越大，首次打开和版本更新时的下载时间越长。控制代码包体积是启动性能优化中最有效的手段之一。

#使用分包加载

分包加载是控制启动时代码包体积最有效的方式。通过将小程序拆分为多个分包，启动时只需下载主包，其他分包在需要时再按需加载。分包加载

适合场景：包大小超过 2M 的项目

#优化建议

• 将启动不需要的页面放入分包
• 主包只保留必要的公共资源和启动页面
• 合理规划分包结构，避免单个分包过大

#移除无用代码和资源

随着项目迭代，代码包中可能积累了大量不再使用的代码和资源文件。

#排查方法

1. 检查未引用的页面：app.json 中注册但实际未使用的页面
2. 检查未引用的组件：JSON 中声明但未使用的自定义组件
3. 检查未引用的资源：项目中存在但没有被引用的图片、字体等文件
4. 检查未使用的依赖：package.json 中安装但未使用的 npm 包

#构建依赖分析

@ray-js/cli 提供了构建依赖分析能力，可以可视化查看各模块在产物中的体积占比，帮助快速定位体积异常的依赖包。Ray构建依赖分析。

#图片和资源优化

图片和资源文件通常是代码包体积的大头。

#图片上传到 CDN

开发者可以将项目中的静态资源(如图片、音频等)上传到 CDN，运行时会自动替换为对应的 CDN 地址，减少图片体积占用。涂鸦 CDN 使用指南。

#图片压缩

如果必须使用本地图片，建议：

• 使用合适的图片格式
• 避免 base64 内联大资源
• 使用工具压缩图片（如 Tinypng）
• 控制图片尺寸，避免使用超出显示需要的大尺寸图片

#对依赖的选择和引入

选择依赖包时，关注包的体积大小：

// 推荐：使用轻量工具库
import dayjs from 'dayjs'; // ~2KB

// 避免：使用重量级库
import moment from 'moment'; // ~70KB

对于支持按需引入的库，避免全量导入：

// 推荐：按需引入
import debounce from 'lodash/debounce';

// 避免：全量引入
import { debounce } from 'lodash';

#去 react-dom

环境要求：@ray-js/ray >= 1.7.39

Ray 的较新版本已去除错误引入的 react-dom 依赖，升级后业务包可减少 100k+ 的体积。如果当前版本较旧，升级 Ray 版本即可生效。

#去除冗余 iconfont

环境要求：@ray-js/ray >= 1.6.0

旧版本中，任何引用了 @ray-js/ray 的页面都会将 iconfont.css 全量打包进去，导致每个页面都带上了一份多余的字体样式。升级到 @ray-js/ray >= 1.6.0 后，iconfont.css 改为按需引入，仅在实际用到图标时才会打包，可明显减少包体积。

// `@ray-js/ray@1.6.0` 版本之后不再内置 Icon 组件，需要单独安装 `@ray-js/icons`
import { Icon } from '@ray-js/icons';

#按需加载 Smart-UI

适用场景：使用 Smart-UI 的项目

环境要求：

• @ray-js/cli >= 1.7.4
• esbuild 构建模式（不支持 webpack）
• 使用 ESModule import 语法
• SmartUI >= 2.4.0

配置后构建时会自动将 Smart-UI 的全量导入转换为按需导入，降低包体积。在 ray.config.ts 中增加 importTransformer 配置：

import { RayConfig } from '@ray-js/types';
import SmartUIAutoImport from '@ray-js/smart-ui/lib/auto-import';

const config: RayConfig = {
  // ...
  importTransformer: [SmartUIAutoImport],
};

export default config;

配置后效果：

// 构建前
import { Button } from '@ray-js/smart-ui';

// 构建后（自动转换）
import { Button } from '@ray-js/smart-ui/es/button';

#检查清单