---
title: 代码包体积优化
summary: "介绍代码包体积优化方法，包括分包加载、依赖瘦身、图片上传 CDN 和按需加载。"
docType: default
tags: [代码包体积优化, 分包加载配置, npm依赖瘦身, 主包体积控制]
questions:
  - 为什么代码包体积会影响小程序启动性能？
  - 如何使用分包加载控制启动时的代码包体积？
  - 如何排查和移除项目中的无用代码和资源？
  - 如何通过将图片上传到 CDN 来减小代码包体积？
  - 选择第三方依赖包时应该注意什么？
  - 升级 Ray 版本如何去除 react-dom 和冗余 iconfont？
  - 如何配置 Smart-UI 的按需加载？
  - 构建依赖分析工具如何帮助定位体积问题？
---

# 代码包体积优化

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

## 使用分包加载

分包加载是控制启动时代码包体积最有效的方式。通过将小程序拆分为多个分包，启动时只需下载主包，其他分包在需要时再按需加载。[分包加载](/cn/miniapp/develop/miniapp/guide/ability/sub-packages)

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

### 优化建议

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

## 移除无用代码和资源

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

### 排查方法

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

### 构建依赖分析

`@ray-js/cli` 提供了构建依赖分析能力，可以可视化查看各模块在产物中的体积占比，帮助快速定位体积异常的依赖包。[Ray构建依赖分析](/cn/miniapp/develop/ray/guide/optimization/startup/bundle-analysis)。

## 图片和资源优化

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

### 图片上传到 CDN

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

### 图片压缩

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

- 使用合适的图片格式
- 避免 base64 内联大资源
- 使用工具压缩图片（如 [Tinypng](https://tinypng.com/)）
- 控制图片尺寸，避免使用超出显示需要的大尺寸图片

## 对依赖的选择和引入

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

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

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

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

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

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

## 去 react-dom

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

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

<Image src="/images/guide/optimization/react-dom-bundle.png" width="600px" />

## 去除冗余 iconfont

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

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

```js
// `@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` 配置：

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

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

export default config;
```

配置后效果：

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

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

## 检查清单

| 检查项 | 优化方法 |
| ------ | -------- |
| 包体积是否超过 2MB | 使用分包加载，启动时只下载主包 |
| 是否有未引用的依赖、组件、资源 | 使用构建依赖分析排查并删除 |
| 是否引入了体积过大的第三方库 | 替换为轻量库，或使用按需引入 |
| 是否有本地图片资源 | 上传到 CDN/压缩后引用 |
| 是否全量引入了 Smart-UI | 配置 importTransformer 开启按需加载 |
| Ray 版本是否过旧 | 升级到 >= 1.6.0 去除冗余 iconfont；升级到 >= 1.7.39 去除 react-dom 依赖 |