Uni-app mini program images stuck in static in 2026: can you catch the main package overrun before review?

1. Start with the conclusion: a main package overrun is usually not because you wrote too much business code

Based on 2026 project delivery experience, when a Uni-app mini program build reports a main package overrun, the root cause is usually not too much business logic. It is more often static assets that were never moved out, third-party dependencies imported as whole packages, or every page being attached to the main package. Measure the size distribution first, then decide whether to remove dependencies or split packages: if the overage past the platform limit is relatively small, moving assets, switching to on-demand imports, and changing compression methods is often enough; only when the overage approaches half the limit or more do you need to change the subpackage structure. Based on the experience range, cleaning up assets and dependencies alone often reduces the package by tens of KB to several hundred KB, depending on how many images the project has packed in.

In typical projects, for a medium-sized mini program, business JS often takes up only a small part of the main package. What really consumes size is static assets such as large images, fonts, and video covers, plus dependencies imported as whole packages when only one or two of their features are used. So the first step is not deleting code — it is measuring.

2. In the same Uni-app project, why H5 does not get stuck but the mini program does

Mini programs and H5 use different loading models: H5 downloads and renders as it goes, so a larger size feels slow to users; a mini program must download the package locally before it can start, so the larger the main package, the longer the wait before first open, and the gap is amplified on weak networks and low-end Android devices. With the same codebase, H5 may never have issues while the mini program gets stuck at the review step — this is usually why.

The harder layer is platform rules: according to the official WeChat Mini Program documentation, the typical main package size limit is around 2MB, and the typical total limit across all subpackages is around 20MB. Check each platform's latest specification for the exact numbers, and verify against the official documentation before delivery. Going over the limit is not just slightly worse performance — the package cannot be uploaded and cannot pass review. It is a process blocker, not a pure optimization issue.

• First-open wait: The larger the main package, the longer new users wait on their first visit, and the more obvious the drop-off.
• Review approval: Exceeding the limit means the package cannot be uploaded at all, pushing the release schedule back.
• Startup on low-end devices: At the same size, the perceived gap is larger on low-end devices.

3. Remove dependencies or split packages: a checkable comparison

These are not either-or choices; it is a question of order. Below is a comparison based on typical benefit and schedule ranges seen in projects. The numbers vary with project scale and should only be used as reference, not copied directly.

1. Move static assets to CDN: Typical main package savings are tens of KB to several hundred KB, with a typical schedule of half a day to 1 working day. The trade-off is re-verifying weak-network first screen and image reference methods; images with runtime-built paths are easy to miss.
2. Switch dependencies to on-demand imports: Typical savings are tens of KB to one or two hundred KB, with a typical schedule of 0.5 to 1 working day. The trade-off is that some libraries have interface differences after on-demand configuration, so affected pages need regression testing.
3. Regular subpackage splitting: Typical main package savings are several hundred KB or more, with a typical schedule of 1 to 3 working days. The trade-off is that navigation paths, tabBar configuration, and ownership of shared components all need to change, with higher rework cost than the first two options.
4. Independent subpackages and subpackage async: Benefits depend on the scenario, with a typical schedule of 2 to 5 working days. The trade-off is that shared libraries may be packed repeatedly, the total package is not necessarily smaller, and configuration is more convoluted.

A simple rule of thumb: if a low-risk fix can solve it, do not rush to change the routing structure. Changing the structure affects navigation and subpackage configuration, and if you get it wrong, troubleshooting costs far more than moving a few images.

4. The three things that really eat the main package, handled in order

4.1 Static assets: move first, do not delete first

Files such as large images, fonts, audio, and video covers should be moved to CDN first, or loaded on demand from subpackages. Note that changing only the local directory is not enough — image paths built at runtime often cannot be split correctly. Confirm the reference method before moving; otherwise the local build looks smaller but the files are still in the production package.

4.2 Dependencies: whole-package imports are a common big contributor

When UI libraries, chart libraries, and utility libraries are imported as whole packages, unused modules also enter the package. In 2026, most mainstream libraries offer on-demand imports or subpackage exports, and changing configuration is usually easier than splitting pages. Be aware that interfaces may differ slightly after switching to on-demand, so run regression on affected pages afterward.

4.3 Pages: split by visit frequency, not by tidy folder structure

tabBar pages, startup pages, and tiered entry pages should stay in the main package; their size cannot be split away. Other low-frequency pages, campaign pages, and QR-code landing pages can go into subpackages. The test is simple: will users click through from the home page? If yes, keep it in the main package; if it is reached directly by QR scan or sharing, then consider an independent subpackage.

5. What size cannot be split away — do not pin all your hopes on subpackages

tabBar pages, startup pages, shared components, and libraries used by multiple subpackages usually all need to stay in the main package or somewhere visible to the main package. Independent subpackages can run independently but cannot depend on main package resources, so shared libraries must be packed repeatedly. The typical result is a smaller main package and larger subpackages, not necessarily a smaller total package. When unsure, set a budget that leaves roughly 10% headroom in the main package instead of running right up against the limit; otherwise one campaign page plus two images will push it over again.

One more easily overlooked point: review looks at the production package, and its measurement basis may differ from the local artifacts seen during development; debug code and source maps can both be mixed in. So measure the production package, not the development build.

6. Delivery reality: how one review rework happens

A common constraint looks like this: the schedule is tight, operations requires the home carousel and first-screen campaign images to be high-resolution, the assets arrive from the client at the last minute, and there is no time to compress them. The quick fix at the time was to drop the images straight into the static directory. Everything ran fine locally, but only at review time did the main package overrun appear and the package fail to upload. The cost was moving the images to CDN on short notice, redoing image references, and running device verification again — roughly 1 to 2 extra working days overall, with the campaign launch pushed back as well.

Based on the 2026 delivery experience range, rework caused by 'assets not moved out' typically takes half a day to two days; if it involves the subpackage structure, it typically takes 1 to 3 working days. So before delivery, check three things: whether static assets are in the right place, whether references can be split correctly, and how much main package headroom remains. These three checks do not take long but can save one round of review rework.

7. Where it applies and where it does not

Subpackage splitting is not mandatory for every Uni-app project. The test can be reduced to one sentence: is the main package already close to the platform limit, and are there clear low-frequency pages or large assets? If neither is true, forcing a split only makes routing and navigation more error-prone.

• Worth splitting: Multi-page e-commerce, content sites, frequent campaign operations, or projects that must ship mini program, App, and H5 together; many pages, large static assets, and a main package already close to the limit.
• Not necessary to split: Single-page tools, mini programs with single-digit page counts, and lightweight mini programs with few dependencies; when maintained by one or two people, the path complexity from splitting may outweigh the benefit.
• When unsure: If App and H5 must also ship, base the subpackage strategy on the side with worse perceived performance — usually the mini program.

FAQ

When a Uni-app main package is over the limit, should I remove dependencies first or split packages first?

Look at the measured proportions first. If dependencies and static assets are the biggest share, move assets and switch to on-demand imports first; if business pages are the biggest share, then consider subpackages. Reversing the order often wastes a round of changes.

How much does putting images in the static directory versus CDN affect the main package?

Moving files such as large images and fonts to CDN typically reduces the main package by tens of KB to several hundred KB. The trade-off is an extra network request, and the weak-network first screen may become slower, so weigh it by page importance.

Do independent subpackages always save more size than regular subpackages?

Not necessarily. Independent subpackages cannot share main package resources, and shared libraries must be packed repeatedly. The typical result is a smaller main package and larger subpackages, so the total package may not be smaller. Judge by the overall total.

It runs fine on a local device, but review still reports an overrun. What are the common causes?

Common causes are different measurement bases between the development build and the production package, or debug code and extra source maps mixed into the package. Before review, use tooling to measure the production package size distribution again.

For a component used by multiple subpackages, should it go in the main package or a subpackage?

If only one subpackage uses it, put it in that subpackage; if multiple subpackages share it, put it in the main package or create a separate shared subpackage. Putting it in the main package increases main package size, so weigh it by size and call frequency.

If you need to submit for review this month, first measure the main package size: if asset compression and on-demand imports can solve it, do not rush to change the routing structure; only if there truly are many pages and large assets should you split subpackages by visit frequency. One reminder: for lightweight mini programs or solo-maintained projects, the benefit of splitting is limited, and prioritizing asset reduction is usually the better value.