uni-app iOS Build: Cloud Build or Local Build on Windows
For a uni-app iOS build, use DCloud cloud build early on or for paid native plugins; switch to a local offline SDK build on Windows for native debugging.
For a uni-app iOS build, choose the DCloud cloud build from HBuilderX when the project is new, you build only occasionally, or you rely on paid native plugins from the plugin market. Choose a local build with the offline SDK when you’re debugging native features many times a day, integrating your own native SDK, or can’t wait in a queue or live with build limits. The two can coexist: many teams build locally during development and use the cloud build for release. Cloud build rules follow DCloud’s official docs as of October 2026.
What’s the difference between a cloud build and a local build?
| DCloud cloud build | Local build (offline SDK) | |
|---|---|---|
| Where it builds | DCloud’s cloud build machines | Your own computer |
| Build environment | Maintained by DCloud, nothing to install | You set it up. The official flow uses Xcode on a Mac. On Windows and Linux you can use KXBuild |
| Queue | You may wait at peak times. Free build machines for older HBuilderX versions are being reduced, so queues there get longer | No queue |
| Limits and cost | Free quota limited per day and per month (exact rules aren’t published). Beyond that you pay per build, and large projects are charged by size | Unlimited builds, no build fee to DCloud |
| Certificates | You upload the .p12, its password and the .mobileprovision with each build | Certificates and profiles stay on your machine |
| Native plugins | Supports native plugins from the plugin market, including paid ones | Integrate any native SDK and your own native code. Per DCloud’s docs, paid native plugins from the plugin market can’t be used in offline builds |
| Native obfuscation | Supported | Not available, per DCloud’s docs |
| Debugging | Standard base, custom base and the HBuilderX debugger | Run on the iPhone right from HBuilderX and push page changes to the phone in seconds. Breakpoints in native code. Page JS still uses the HBuilderX debugging tools |
| Config changes | After changing native settings in manifest.json, rebuild the custom base or the release build | Run on the iPhone again |
| Setup | Sign in with a DCloud account | Install KXBuild and its HBuilderX plugin, download the offline SDK matching your HBuilderX version and apply for an offline build AppKey |
Both need an Apple Developer account, a certificate and a provisioning profile. To request a certificate and export a .p12 on Windows, see Get an iOS certificate, p12 and provisioning profile on Windows.
What are the cloud build limits and fees?
The points below come from DCloud’s cloud build docs and the February 5, 2026 billing change announcement, both in Chinese. The rules change from time to time, so check the official pages before you build.
- Build modes. A traditional build uploads your code and certificates to DCloud’s servers, which DCloud says are cleaned up automatically after the build. A safe build uploads neither and is faster, but according to the safe build docs, iOS safe builds only run on macOS. iOS cloud builds from Windows use the traditional mode.
- Build count. Each account gets a free quota with daily and monthly limits, and the risk-control rules aren’t published. When you run out, top up in the DCloud developer center and pay CNY 2 per build. A build counts as soon as it’s submitted to the server, whether it succeeds or fails.
- Size. Projects whose raw size (after compiling, before compressing, including front-end code, images and local native plugins) exceeds 60 MB are charged by size, separately for Android and iOS. Generating iOS symbol files also costs extra.
- Queue. You may wait at peak times. DCloud offers two ways to speed things up, dedicated build machines billed per build and enterprise build machines billed per year.
To save builds, use the standard base or a custom base while developing so you make fewer release builds, and keep HBuilderX up to date for shorter queues.
When should a uni-app iOS build use the cloud?
- The project is just starting, you build a few times a week and the free quota is enough.
- You use paid native plugins from the plugin market, or need native obfuscation to protect your JS code.
- Nobody on the team wants to maintain a local iOS build environment.
- You need Android and iOS builds at the same time and want the cloud to handle both.
When should I build locally?
- You’re working on native modules such as push, payments or maps and build many times a day.
- You need a native SDK that isn’t in the plugin market, or you need to change native code.
- Native crashes need breakpoints and a call stack.
- A release is due and you can’t wait in a queue.
- Your company requires code and certificates to stay on the internal network.
How do I make a local uni-app iOS build on Windows?
DCloud’s official offline build flow uses Xcode on a Mac. On Windows you can do the same steps with KXBuild. Here is the outline. For the details of each step, see Package a uni-app iOS app offline on Windows, no cloud build queue.
| Step | What to do |
|---|---|
| 1 | Download the iOS offline SDK zip matching your HBuilderX version. Don’t unzip it |
| 2 | In the DCloud developer center, apply for an offline build AppKey for your Bundle ID, and register an App ID with the same Bundle ID in the Apple Developer portal |
| 3 | In HBuilderX, set the name, version, icons, permission descriptions and modules in manifest.json |
| 4 | Install KXBuild and the HBuilderX plugin |
| 5 | Connect your iPhone and choose “运行 → 运行到 iPhone 真机 (KXBuild)” (Run on iPhone) in HBuilderX. The first time, enter the Bundle ID and AppKey and select the SDK zip when asked |
| 6 | Choose “发行 → 生成 iOS 发布版 ipa (KXBuild)” (Build release .ipa) and upload the .ipa to App Store Connect |
After that, when you’ve only changed pages, use “运行 → 推送页面到 iPhone (KXBuild)” (Push pages to iPhone). It takes a few seconds and keeps the app’s data. After changing native settings in manifest.json, run on the iPhone again. You don’t need to rebuild a custom base. To package from a script, export the Xcode project with the uniapp2xcode command and build it.
How do I troubleshoot build errors?
| Symptom | Cause | Fix |
|---|---|---|
| The local build shows an AppKey error on launch | The AppKey is missing, or the Bundle ID used to apply for it doesn’t match the project | Check the iOS package name in the developer center, fix the Bundle ID and AppKey in the plugin and run again |
| The local build shows a version mismatch or a blank screen | The offline SDK and HBuilderX versions differ | Download the SDK matching your current HBuilderX, import it and run again |
| The local build breaks after upgrading HBuilderX | The SDK wasn’t upgraded with it | Switch to the matching SDK every time you upgrade HBuilderX |
| The cloud build says the certificate and profile don’t match | The .p12 and .mobileprovision aren’t a pair, or the Bundle ID differs | Regenerate the profile with the same certificate and make the Bundle ID match manifest.json |
| The cloud build won’t install on the phone | A Development profile doesn’t include the phone’s UDID, or the certificate type is wrong | Add the UDID to the profile and download it again. For the App Store, use a Distribution certificate and an App Store profile |
| The local export says a module was skipped | The current offline SDK doesn’t have the module, or its library can’t be linked | The other modules build as usual. Wait for DCloud to release a fixed SDK |
| The local build crashes when opening the camera | Info.plist is missing a privacy description | Add it in the App permissions section of manifest.json and run again |
The AppKey, the Bundle ID and the App ID in the Apple Developer portal belong together and must match exactly. Cloud and local uni-app iOS builds can share the same Bundle ID, so you don’t need to change it when you switch.
FAQ
How many uni-app cloud builds can I run per day?
DCloud gives each account a free quota with daily and monthly limits, but the exact rules aren’t published. When you run out, top up in the developer center and pay CNY 2 per build. A build counts once it’s submitted, even if it fails.
Can I build a uni-app iOS app locally on Windows?
Yes. DCloud’s official offline flow uses Xcode on a Mac. On Windows you can install the KXBuild plugin for HBuilderX to run on your iPhone, push pages and produce an .ipa right from HBuilderX, as shown in the uni-app offline build tutorial.
Does the offline SDK version have to match HBuilderX?
Yes. If the versions differ, the app shows a version mismatch or a blank screen on launch. Every time you upgrade HBuilderX, download the matching offline SDK and import it once.
Where do I get the offline build AppKey?
Sign in to the DCloud developer center at dev.dcloud.net.cn, open the app under My Apps, add the iOS platform in the platform info and enter your Bundle ID. After you save, the offline build key is shown. The Bundle ID must match the App ID in the Apple Developer portal.
Can I use paid native plugins from the plugin market in an offline build?
No. DCloud’s safe build docs say paid native plugins from the plugin market can’t be used in offline builds for copyright reasons, and native obfuscation isn’t available either. If your project uses such plugins, keep making release builds in the cloud.