真机调试失败大概率因主包超2mb，需检查vendor.js和app.js总和；启用subpackages、按需引入第三方库、静态资源走cdn可有效压缩体积。
真机调试失败时先看主包体积是否超 2MB
微信小程序真机调试失败、生成不了二维码，大概率是主包体积已超 2MB。这不是报错提示里明说的“包太大”，而是静默失败——开发者工具不报错，但手机扫不出码、调试器连不上。打开「详情 → 代码依赖分析」，重点盯 vendor.js 和 app.js 大小，这两个文件加起来超过 2MB 就会卡死。
启用 subPackages 优化让 vendor.js 拆分到分包
很多项目只配了 subPackages 目录结构，但没在 manifest.json 里开启构建级分包支持，导致所有依赖仍被塞进主包的 vendor.js。必须手动补上：
{
"mp-weixin": {
"optimization": {
"subPackages": true
}
}
}
改完后重启 HBuilderX 或重新运行 npm run dev:mp-weixin，再进代码依赖分析——你会看到原来独占 1.8MB 的 vendor.js 缩到 300KB 左右，同时各分包目录下出现自己的 vendor.js。这是最立竿见影的一步，但前提是分包目录结构已正确定义。
第三方库必须按需引入，否则 tree shaking 失效
uni-app 默认用 modules: 'commonjs'，加上自定义组件编译模式，导致 import { debounce } from 'lodash' 这类写法依然会把整个 lodash 打进去。实际生效的写法只有两种：
-
import debounce from 'lodash/debounce'（路径必须精确到文件） - 换用
lodash-es并确保未被 babel 转成 commonjs（检查vite.config.ts或vue.config.js中transformIgnorePatterns是否放过node_modules/.pnpm/.*lodash-es）
像 moment、dayjs 这类时间库，直接全局 import moment from 'moment' 会吃掉 200KB+，换成 import dayjs from 'dayjs' + 插件按需加载（如 dayjs/plugin/relativeTime）才安全。
静态资源别放 static，图片字体一律走 CDN
很多人以为 static 目录只是“本地缓存快”，实际上它全被打进主包。一张未压缩的 500KB 背景图，就能让主包直接突破上限。真实可行的做法是：
- 所有大于 10KB 的图片、SVG、字体文件，上传到 CDN，用
https://地址引用 -
static下只留必要图标：tabBar 图标、启动页 logo、极小尺寸 icon（ - 如果必须本地加载，用
uni.uploadFile+ 本地缓存逻辑，而不是打包时带进去
这步省下的空间往往比代码优化更可观——一个 800KB 的 banner 图，删掉就立刻腾出主包 40% 容量。
真正卡住人的不是配置本身，而是 subPackages: true 开启后，某些跨分包引用的组件或 store 实例没做适配，导致白屏；或是 CDN 图片没加域名白名单，开发工具能跑、真机就 404。这些细节不验证，光调体积数字没用。
