小程序主包体积优化 - 路径迁移修复实战

前言

在最近的优化项目中，我们成功将小程序主包体积减少了约 300KB。主要的优化手段是将部分主包页面迁移到分包中，但这也带来了一个棘手的问题------所有指向这些页面的路径引用都需要更新。本文记录了这次路径修复的完整过程。

优化背景

小程序对主包大小有严格限制（2MB），当主包体积过大时会影响首屏加载速度。我们通过将部分非核心页面迁移到分包来优化主包体积。

迁移的页面

页面类型	原路径	新路径
登录注册	pages/login/*	subPages/auth/*
经营管理	pages/business/*	subPages/business/*
店铺入驻	pages/storeJoin/*	subPages/storeJoin/*
订单重定向	pages/order/orderRedirct	subPages/orderRedirect/order/orderRedirct

问题发现

迁移完成后，通过自动化脚本发现代码中存在大量旧路径引用：

./validate-paths.sh

发现的问题：

• ❌ 27个文件中存在旧路径引用
• ❌ 174行需要更新的导航代码
• ❌ 多处组件导入路径错误

解决方案

1. 路径映射表

首先建立完整的路径映射：

原路径	新路径
/pages/login/register/register	/subPages/auth/register/register
/pages/login/resetPassword/resetPassword	/subPages/auth/resetPassword/resetPassword
/pages/business/business/business	/subPages/business/business/business
/pages/business/editProduct/editProduct	/subPages/business/editProduct/editProduct
/pages/storeJoin/storeJoin/storeJoin	/subPages/storeJoin/storeJoin/storeJoin
/pages/storeJoin/joinFail/joinFail	/subPages/storeJoin/joinFail/joinFail
@/pages/storeJoin/storeJoin/constants	@/subPages/storeJoin/storeJoin/constants

2. 批量修复

使用 sed 命令进行批量替换：

# 修复登录相关路径
find src/ -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.js" \) -print0 | \
xargs -0 sed -i '' 's|/pages/login/register/register|/subPages/auth/register/register|g'

# 修复经营管理路径
find src/ -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.js" \) -print0 | \
xargs -0 sed -i '' 's|/pages/business/business/business|/subPages/business/business/business|g'

# 修复入驻页面路径
find src/ -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.js" \) -print0 | \
xargs -0 sed -i '' 's|/pages/storeJoin/storeJoin/storeJoin|/subPages/storeJoin/storeJoin/storeJoin|g'

3. 特殊处理

对于组件导入路径，需要特别处理 @ 别名：

# 修复常量导入路径
find src/ -type f \( -name "*.vue" -o -name "*.ts" -o -name "*.js" \) -print0 | \
xargs -0 sed -i '' 's|@/pages/storeJoin/storeJoin/constants|@/subPages/storeJoin/storeJoin/constants|g'

修复结果

统计数据

• 修改文件数: 27个
• 代码变更: 174行新增, 132行删除
• 验证结果: ✅ 所有路径验证通过

主要修复文件

登录相关 (auth分包)

• src/subPages/auth/login/login.vue
• src/subPages/auth/register/register.vue
• src/pages/login/index/index.vue

经营管理相关 (business分包)

• src/subPages/business/business/business.vue
• src/subPages/business/editProduct/editProduct.vue
• src/subPages/business/productScheduling/productScheduling.vue

入驻相关 (storeJoin分包)

• src/subPages/storeJoin/storeJoin/storeJoin.vue
• src/subPages/storeJoin/joinFail/joinFail.vue
• src/pages/my/my.vue
• src/pages/myPages/setting/setting.vue

验证方法

创建验证脚本 validate-paths.sh：

#!/bin/bash

# 验证主包页面
main_pages=(
  "pages/login/index/index.vue"
  "pages/create/create.vue"
  "pages/order/order.vue"
  "pages/orderSupplier/order.vue"
  "pages/my/my.vue"
)

# 验证分包页面
sub_pages=(
  "subPages/auth/login/login.vue"
  "subPages/auth/register/register.vue"
  "subPages/business/business/business.vue"
  "subPages/storeJoin/storeJoin/storeJoin.vue"
)

# 检查文件是否存在
# 检查代码中的旧路径引用
# 验证组件路径

运行验证：

chmod +x validate-paths.sh
./validate-paths.sh

经验总结

✅ 做对的事情

1. 先验证后修复 - 使用脚本全面扫描问题
2. 建立路径映射 - 系统化地管理变更
3. 批量处理 - 使用 sed 提高效率
4. 自动验证 - 修复后立即验证结果

⚠️ 注意事项

1. 路径引用的多样性

   • 导航路径: url: '/pages/xxx'
   • 组件导入: @/pages/xxx
   • 相对路径: ../pages/xxx

2. pages.json 配置

   {
     "subPackages": [
       {
         "root": "subPages/auth",
         "pages": [...]
       }
     ]
   }

3. easycom 组件路径

   • 删除未使用的组件
   • 更新组件引用路径

📚 最佳实践

1. 使用绝对路径 - 便于重构和迁移
2. 统一路径别名 - 避免硬编码相对路径
3. 自动化验证 - 集成到 CI/CD 流程
4. 文档化变更 - 维护路径映射表

下一步

# 1. 测试应用功能
npm run dev:mp-weixin

# 2. 检查构建
npm run build:mp-weixin

# 3. 提交代码
git add .
git commit -m "fix: 修复分包迁移后的路径引用"

相关资源

• uni-app 分包加载文档
• 小程序分包指南

---

修复时间 : 2025-12-25
修复结果 : ✅ 成功
主包优化: -300KB