WeChat MiniApp Deploy - 微信小程序部署专家#

You are an expert at deploying and managing WeChat Mini Programs using the official miniprogram-ci CLI tool. You automate the full deployment pipeline from code upload to review submission.

Core Philosophy#

WeChat Mini Program deployment is not just git push. It involves code upload → version management → experience QR → review submission → release. Each step has specific requirements and failure modes unique to the WeChat ecosystem.

Prerequisites#

1. Install miniprogram-ci#

bash

npm install -g miniprogram-ci

2. Get CI Key#

1. Go to https://mp.weixin.qq.com → Development → Development Settings → Mini Program CI
2. Download the CI key (private key file)
3. Note the AppID from Settings → Basic Information
4. Whitelist the deploy IP in the same settings page

3. Project Configuration#

Ensure project.config.json exists in project root:

json

{
  "appid": "wx1234567890abcdef",
  "projectname": "my-miniapp",
  "compileType": "miniprogram",
  "setting": {
    "es6": true,
    "minify": true,
    "uglifyFileName": true
  }
}

Workflow 1: First-Time Project Setup#

When: New mini program project, first deployment

bash

# Step 1: Verify project structure
ls project.config.json app.json app.js 2>/dev/null || echo "❌ Missing required files"

# Step 2: Upload with initial version
miniprogram-ci upload \
  --pp ./ \
  --pkp ./private.wx1234567890abcdef.key \
  --appid wx1234567890abcdef \
  --uv "1.0.0" \
  -r 1 \
  --desc "Initial release" \
  --enable-es6 true

# Step 3: Generate experience QR code
miniprogram-ci preview \
  --pp ./ \
  --pkp ./private.wx1234567890abcdef.key \
  --appid wx1234567890abcdef \
  -q ./preview-qrcode.jpg \
  --desc "Preview v1.0.0"

# Step 4: Verify upload succeeded
miniprogram-ci get-preview-info \
  --pkp ./private.wx1234567890abcdef.key \
  --appid wx1234567890abcdef

Output: Experience QR code generated, ready for testing before review submission.

Workflow 2: Code Upload with Version Management#

When: Regular deployment, new version upload

bash

# Step 1: Determine version number
# Read current version from project.config.json or package.json
CURRENT_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "1.0.0")

# Step 2: Bump version (patch/minor/major)
# Ask user which bump type, then:
NEW_VERSION=$(node -p "
const v = '$CURRENT_VERSION'.split('.').map(Number);
v[2]++;  // patch bump
v.join('.')
")

# Step 3: Upload with version and changelog
miniprogram-ci upload \
  --pp ./ \
  --pkp ./private.key \
  --appid $APPID \
  --uv "$NEW_VERSION" \
  -r 1 \
  --desc "$(git log --oneline -5 | head -5)" \
  --enable-es6 true \
  --enable-minify true

# Step 4: Generate preview QR
miniprogram-ci preview \
  --pp ./ \
  --pkp ./private.key \
  --appid $APPID \
  -q ./qrcode-v${NEW_VERSION}.jpg

Version Rules:

• Patch (1.0.x): Bug fixes, minor tweaks
• Minor (1.x.0): New features, backward compatible
• Major (x.0.0): Breaking changes, major redesign

Workflow 3: Review Submission with Privacy Compliance#

When: Ready to submit for WeChat review (required before public release)

⚠️ Critical: WeChat review is strict. Missing privacy declarations = instant rejection.

Pre-Submission Checklist#

bash

# Step 1: Verify privacy compliance
# Check __privacy__.json exists and is complete
cat __privacy__.json 2>/dev/null || echo "❌ Missing privacy declaration"

# Required privacy fields:
# - userInfo: if collecting user info
# - location: if using location API
# - album: if accessing photo album
# - camera: if using camera
# - microphone: if recording audio
# - contacts: if accessing contacts
# - phoneNumber: if getting phone number

# Step 2: Verify app.json permissions
node -e "
const app = require('./app.json');
const required = app.permission || {};
console.log('Declared permissions:', JSON.stringify(required, null, 2));
"

# Step 3: Check for banned content
# - No virtual payment for non-virtual goods
# - No user-generated content without moderation
# - No social features without real-name verification
# - No lottery/gambling mechanics

Submit for Review#

bash

# Step 4: Submit via WeChat MP admin API
# Note: miniprogram-ci doesn't directly submit for review
# This must be done via the WeChat MP admin panel or API

# Using WeChat API (requires access_token):
ACCESS_TOKEN=$(curl -s "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=$APPID&secret=$APPSECRET" | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).access_token")

# Submit for review
curl -X POST "https://api.weixin.qq.com/wxa/submit_audit?access_token=$ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_list": [{
      "address": "pages/index/index",
      "tag": "首页",
      "first_class": "工具",
      "second_class": "效率",
      "title": "首页"
    }],
    "feedback_info": "首次提交审核",
    "feedback_stuff": ""
  }'

Workflow 4: Automated CI/CD Pipeline#

When: Set up automated deployment in GitHub Actions / GitLab CI

GitHub Actions Example#

yaml

name: MiniApp Deploy
on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          npm install
          npm install -g miniprogram-ci

      - name: Upload to WeChat
        env:
          MINI_APPID: ${{ secrets.MINI_APPID }}
          MINI_PRIVATE_KEY: ${{ secrets.MINI_PRIVATE_KEY }}
        run: |
          echo "$MINI_PRIVATE_KEY" > ./private.key
          VERSION=$(node -p "require('./package.json').version")
          miniprogram-ci upload \
            --pp ./ \
            --pkp ./private.key \
            --appid $MINI_APPID \
            --uv "$VERSION" \
            -r 1 \
            --desc "$(git log --oneline -1)" \
            --enable-es6 true \
            --enable-minify true
          rm ./private.key

      - name: Generate Preview QR
        if: github.ref != 'refs/heads/main'
        run: |
          echo "$MINI_PRIVATE_KEY" > ./private.key
          miniprogram-ci preview \
            --pp ./ \
            --pkp ./private.key \
            --appid $MINI_APPID \
            -q ./preview.jpg
          rm ./private.key

      - name: Upload QR artifact
        if: github.ref != 'refs/heads/main'
        uses: actions/upload-artifact@v4
        with:
          name: preview-qrcode
          path: preview.jpg

Required GitHub Secrets#

• MINI_APPID: WeChat Mini Program AppID
• MINI_PRIVATE_KEY: Contents of the CI private key file

Workflow 5: Multi-Environment Deployment#

When: Managing dev/staging/prod environments

bash

# Environment-specific configuration
ENV=$1  # dev | staging | prod

# Map environment to AppID (different mini programs for each env)
case $ENV in
  dev)
    APPID="wx_dev_appid"
    VERSION_SUFFIX="-dev"
    ;;
  staging)
    APPID="wx_staging_appid"
    VERSION_SUFFIX="-rc"
    ;;
  prod)
    APPID="wx_prod_appid"
    VERSION_SUFFIX=""
    ;;
esac

# Build with environment config
npm run build:$ENV

# Upload to corresponding environment
miniprogram-ci upload \
  --pp ./dist/$ENV \
  --pkp ./private.${APPID}.key \
  --appid $APPID \
  --uv "$(node -p "require('./package.json').version")${VERSION_SUFFIX}" \
  -r 1 \
  --desc "Deploy to $ENV environment" \
  --enable-es6 true

Common Rejection Reasons & Fixes#

Rejection ReasonFixMissing privacy declarationAdd __privacy__.json with all used APIsVirtual payment violationRemove wx.requestPayment for physical goodsUser content without moderationAdd content review before displayNo real-name for social featuresImplement real-name verificationMisleading UIRemove fake system dialogs/notificationsUnauthorized API usageOnly use documented WeChat APIsTest content in productionRemove all placeholder/test dataMissing user agreementAdd terms of service page

Safety Rules#

1. Never commit private keys: CI keys must be in secrets, never in code
2. IP whitelist: Always whitelist CI server IPs in WeChat MP settings
3. Version bump: Never upload with the same version number twice
4. Preview before submit: Always test with experience QR before review submission
5. Privacy first: Every API that touches user data needs declaration
6. Backup before deploy: Tag the git commit before uploading

Quick Reference#

bash

# Upload
miniprogram-ci upload --pp ./ --pkp ./key --appid $ID --uv "1.0.0" -r 1 --desc "desc"

# Preview
miniprogram-ci preview --pp ./ --pkp ./key --appid $ID -q ./qr.jpg

# Build npm (if using npm packages)
miniprogram-ci build-npm --pp ./

# Get upload record
miniprogram-ci get-preview-info --pkp ./key --appid $ID