12 Must‑Know Mini Program Tips to Avoid Common Pitfalls

1. Plugin Development and Relative Paths

When developing plugins, custom components must be referenced using relative paths.

{
  "usingComponents": {
    "alert": "../../components/alert/alert"
  }
}

2. Obtaining Mini Program QR Code

The page used to generate a QR code via the API must be already released.

After generating the QR code, you can test the scene parameter by scanning it in the developer tools.

3. Swiper Component current Not Resetting

If a swiper-item list is modified (e.g., arr=[1,2] becomes arr=[2]) while current is 1, the swiper may show a blank area because current is not reset to 0; you need to set it manually.

4. Template Message Limits

Timeliness: one payment can send up to 3 messages, one form submission can send 1 message (valid for 7 days).

Correspondence: the openId and formId must match the message recipient.

Acquisition: messages are triggered by payment or form submission.

5. Subpackage Loading Size Limits

When using subpackages, plugins placed inside a subpackage count toward the subpackage’s 2 MB limit and the overall 8 MB package limit, but not the main package’s 2 MB limit (previously counted, now fixed).

6. How to Obtain unionId (including openId)

Prerequisite: the Mini Program or its associated public account must be linked to a WeChat Open Platform account.

If the public account (same entity) is linked and the user follows it: Call wx.login() to get a code , then the backend exchanges appid + appsecret + code for openId , session_key , and unionId .

If the Open Platform links directly to the Mini Program: After user authorization, call wx.getUserInfo() to obtain iv and encryptedData , then decrypt with session_key to get unionId , openId , and user info.

7. H5 and Mini Program Navigation

Public account → Mini Program: configure a custom menu to jump to the Mini Program.

Mini Program → H5: use webview (requires business domain configuration; not supported for personal accounts).

Note: Direct H5 ↔ Mini Program navigation is currently not supported.

8. Canvas Native Component Overlapping Custom Overlay

Control visibility with CSS (e.g., hidden).

If the canvas is purely visual, render it to an image and display the image.

9. Custom Overlay Background Scrolling

Method 1: In the opening function, set a flag isScroll to true when the custom dialog is visible, otherwise false, and bind it to scroll-y of a scroll-view.

Method 2: Add catchtouchmove on the top layer to capture touch events.

10. Mini Program Image Sharing Distortion

To avoid distortion or cropping when sharing images, ensure the shared image has a 5:4 aspect ratio.

11. Authorization

wx.authorize

can request all scopes except scope.userInfo; the latter requires a <button open-type="getUserInfo"/> component.

If a user denies a permission, the failure callback is triggered; you can guide the user to settings with wx.openSetting. (The user must delete the Mini Program to be prompted again.)

12. Data Binding

In double curly braces, only variables defined in data or functions declared in wxs can be used.

Base library version: v2.4.0