Comprehensive uni‑app Guide: Overview, Environment Setup, and Development Practices

1. What is uni‑app

uni‑app is a Vue.js‑based framework that allows developers to write a single codebase and compile it to iOS, Android, H5, and many mini‑program platforms (WeChat, Alipay, Baidu, Toutiao, QQ, etc.). It excels in developer count, case count, cross‑platform capability, extensibility, performance, ecosystem, learning cost, and development cost.

More developers and cases

Stronger cross‑platform ability and extensibility

Excellent performance (fast Hybrid loading, Weex native rendering, superior mini‑program performance)

Rich ecosystem (thousands of plugins, NPM support, compatibility with mpvue and Weex components)

Low learning and development cost (standard Vue syntax, no extra learning)

Reduced recruitment, management, and testing costs; HBuilder X boosts productivity

2. uni‑app Environment Setup

2.1 Install HBuilder X

Download HBuilder X from https://www.dcloud.io/hbuilderx.html , choose the appropriate version (Windows/macOS, standard or app‑development edition) and install.

2.2 Create a Project

Two methods are provided:

Using the visual interface of HBuilder X (File → New → Project). Select the uni‑app template, name the project (e.g., uniappdemo ), and create.

Using vue‑cli: npm install -g @vue/cli then vue create -p dcloudio/uni-preset-vue my-project (add #alpha for the Alpha preset).

After creation, run the project in the browser, on a device, or in a mini‑program simulator via HBuilder X’s Run menu.

2.3 App Real‑Device Run

Connect an Android device, enable USB debugging, and select Run → Run to Phone/Simulator in HBuilder X.

2.4 Packaging

Two packaging modes are available:

Cloud packaging : Use HBuilder X → Release → Native App – Cloud Packaging . Provide a certificate, select platforms (app‑plus, h5, mp‑weixin, etc.), and download the generated APK/IPA.

Offline packaging : Install the native SDKs locally and use HBuilder X → Release → Native App – Local Packaging . Recommended for experienced developers.

2.5 Mini‑Program Development

Download the corresponding mini‑program IDE (e.g., WeChat DevTools), configure the service port, and run the project via HBuilder X → Run → Run to Mini‑Program → WeChat DevTools . Set the AppID in manifest.json before publishing.

2.6 H5 Build and Release

Configure the H5 settings in manifest.json , choose the routing mode (hash), and use HBuilder X → Release → Website – H5 Mobile . The output is placed in unpackage/dist/build/h5 for deployment.

3. Layout and Styling

3.1 Flex Layout

uni‑app recommends using Flex layout for cross‑platform consistency. Example CSS:

.box { display: flex; }

Flex containers support properties such as flex‑direction , flex‑wrap , justify‑content , align‑items , etc.

3.2 Background Images

Background images can be used via base64, network URLs, or local paths (prefixed with ~@ ). Images smaller than 40 KB are automatically converted to base64; larger images should be served from a network source. Mini‑programs do not support relative local paths.

.bg { width: 200rpx; height: 200rpx; background-image: url('~@/static/logo.png'); background-size: 100%; }

When the image exceeds 40 KB, convert it to base64 manually or reference it via a remote URL.

Conclusion

The guide concludes with a reminder to join the architecture community for further learning and to share the article.