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