When Uni-app ships both a mini program and an app and platform differences keep piling up, where should you start in 2026?

When Uni-app cross-platform development runs into platform differences, one method should not be used all the way through: when the difference is point-shaped and only affects one line of rendering or one API parameter, conditional compilation is easier; when differences appear in broad patches and repeat across multiple pages, it is time to extract an adapter layer or split platform-specific files. Based on 2026 project delivery experience, conditional compilation branches within ten places on a single page are usually still acceptable. Once the same capability repeats on more than three pages, continuing to pile on branches means the typical range of maintenance cost will exceed what is saved by 'writing one less copy of code.'

First divide platform differences into three types, then decide where to write them

Cross-platform differences usually cluster in three types: rendering presentation layer (styles, units, component hierarchy, safe area), platform capability layer (login, payment, sharing, location, files, push), and structural layer (page stack, subpackages, route parameters, lifecycle trigger order). The three types converge in different ways; handling them mixed together makes changes messier over time.

The test is whether the difference spreads: if it only affects one rendering instance of a single component, it is point-shaped; if the same capability has different API names or return structures on the two platforms, it is surface-shaped; if page splitting, navigation method, or platform review rules cause structural differences, it is volume-shaped. Point-shaped differences are low-cost with conditional compilation; volume-shaped differences with conditional compilation are a trap you set for yourself.

• Point-shaped: unit conversion, isolated style overrides, a single API parameter differing
• Surface-shaped: login, payment, sharing, location, and similar capabilities with different call methods and return structures
• Volume-shaped: page structure, subpackage strategy, navigation, and platform review rule differences
• Decision criterion: if the same difference appears only once or twice, treat it as point-shaped; if it repeats on more than three pages, treat it as surface-shaped or volume-shaped

Why scattered differences cost more schedule time than 'writing one less copy of code'

Cross-platform frameworks save repeated coding, not the differences themselves. A common 2026 delivery mix is 'mini program first, app second, plus a small number of H5 campaign pages.' When three platforms run in parallel, what really eats the schedule is not writing pages, but scattered differences forcing every requirement change to loop back and confirm 'will this break on the other platform.' Once differences are centralized, changing one place affects only one place.

Another reality is that after AI-assisted coding became common, the cost of generating page styles dropped noticeably. People who can converge platform differences into clear interfaces are becoming scarcer, because tools struggle to decide for you whether a branch should stay in business code long term.

• Scattered differences: every change requires full-platform regression, multiplying test cost
• Centralized differences: one capability domain maps to one adapter file, so after a change you only regress that capability
• Handover angle: a newcomer can look at the adapter layer directory and know which features have platform differences
• Opposite case: conditional compilation in templates has no comments, so the next person can only guess which platform it applies to

Three-step triage: first ask whether it can converge, then decide which layer it belongs in

Many engineering problems are not caused by choosing the wrong approach, but by doing things in the wrong order: using conditional compilation from the start, then trying to refactor only after differences accumulate to dozens of places, when the change surface is already large. The following order can be used.

1. Classify: decide whether the difference belongs to the rendering layer, capability layer, or structural layer. Rendering layer differences should first be solved with style isolation or unit conversion, not rushed into branches.
2. See whether it can converge into an interface: if the same capability has consistent semantics across platforms and only differs in implementation, extract it into a unified method (unified login, unified storage, unified request), so callers do not perceive the platform.
3. Check density: point-shaped differences that appear only once or twice can use local conditional compilation; the same capability appearing on more than three pages should use an adapter layer; different page structures and navigation should use platform-specific files or subpackage pages.
4. Leave traces: write clearly for each platform branch 'why' and 'which platform it applies to.' If a conditional compilation block exceeds one screen, split it into a function.

Two cautions: the adapter layer should stay thin, only doing protocol translation, not stuffing business logic into it; do not copy an entire page into a platform-specific file and then edit it, extract the shared parts, otherwise future requirement changes must be made twice.

Delivery scene: that rework caused by scattered differences

A common situation in projects is limited budget and a timeline squeezed into four to six weeks (experience range, varying with page count). The team first writes for H5, then adapts it to the mini program and app, with conditional compilation written directly in page templates; early on it is indeed fast. By pre-launch regression across three platforms, they discover that login state cannot read the cache on the app side and sharing parameters are lost on the mini program side. These two differences are scattered across seven or eight pages, so they can only be checked page by page. Rework takes about two to four person-days more (experience range), and the integration milestone slips by two days. The cost is not in code volume, but in 'no one can clearly say which pages are affected.'

How the three approaches compare side by side

The three approaches are not about right or wrong, but about different applicable ranges. When deciding, look at difference density, testability, and future change frequency, not just how fast it is to write right now.

• Conditional compilation: suitable for point-shaped differences, fast to change and low to start; drawbacks are scattering, difficulty in independent testing, and rising maintenance cost at high density. It is commonly suitable for changes within ten places per page (experience range)
• Adapter layer encapsulation: suitable for surface-shaped capability differences, encapsulating once for multi-platform calls; each capability domain costs about 0.5 to 2 person-days upfront (experience range), in exchange for clean business code and unit testability
• Platform-specific files or subpackage pages: suitable for volume-shaped structural differences, with thorough isolation; the cost is possible duplication of similar logic, requiring someone to maintain the shared parts
• Bundle size dimension: conditional compilation has little impact on package size, while platform-specific files slightly increase it. When approaching the mini program main package limit, consider subpackages or on-demand imports first

Acceptance criteria and applicable boundaries

Whether difference management is good can be judged with several checkable criteria, without relying on feeling.

• Conditional compilation blocks have comments explaining platform and reason, and a single block does not exceed one screen (experience criterion)
• The same capability has only one entry point in the business layer; there is no 'writing both platform APIs directly in the page'
• When adding a new platform, changes are concentrated in the adapter layer and a small number of structural files, while business pages basically stay untouched
• The three-platform regression checklist can be enumerated, so the next person can reproduce difference points from it
• Platform branches are not copied everywhere, and requirement changes do not require 'changing twice'

Suitable for: projects delivering a mini program and an app at the same time (or adding H5), with differences concentrated in login, payment, sharing, location, and other capability domains; projects with continuous iteration, multiple maintainers, and sensitivity to regression cost. Less suitable for: projects shipping only one platform, or one-off campaign pages, where two or three conditional compilation blocks are enough to finish; if differences can be eliminated by a unified design system, fixing the system saves more than writing branches. Boundary sentence: cross-platform frameworks reduce repeated coding, but they do not eliminate platform differences; difference management is an engineering decision, not a built-in framework feature.

Frequently asked questions

How many conditional compilation blocks are too many?

By experience range, if a single page exceeds ten places, or the same capability repeats on more than three pages, extract an adapter layer instead of continuing to add branches.

What usually goes in a Uni-app adapter layer?

Mainly protocol translation: converge multi-platform API differences into unified inputs and outputs, while business decisions stay in the page or state management layer.

Will splitting platform files double the code volume?

After shared logic is extracted into composables or utility functions, platform files keep only the differing parts. In common practice, the increase is about 10% to 20% (experience range).

When the mini program main package exceeds the limit, what should be changed first?

Look first at image assets and third-party libraries, then consider moving non-first-screen pages into subpackages; platform detection code is generally not the main size contributor.

If one person maintains multiple platforms, which approach is recommended?

Prioritize an adapter layer plus a small amount of conditional compilation, and split platform files only for complex structural differences. With single-person maintenance, the real fear is differences scattered across pages.

The next step can be implemented like this: for new projects, decide the adapter layer location while setting up the directory, and first cover four high-frequency capabilities: login, storage, request, and event tracking. Old projects do not need a one-time refactor; proceed by 'new requirements follow new rules, old differences migrate as changes happen.' If you ship only one platform or have very few pages, continuing with conditional compilation is fine, and there is no need to add a layer for it. Centralizing differences is about reducing regression, not writing more code.