Skip to main content

Initial Setup - WeChat Mini Program

This guide provides comprehensive instructions for setting up the WeChat Mini Program development and deployment environment, including WeChat Official Account Platform configuration, developer tools setup, and initial project configuration.

Prerequisites​

Before beginning the setup process, ensure you have:

  • WeChat Account: A valid WeChat account (mobile number required)
  • WeChat Official Account: Access to a WeChat Official Account (订阅号, 服务号, or 企业号)
  • Administrative Access: Admin or developer permissions on the WeChat Official Account
  • Development Environment: Node.js and npm installed on your development machine
  • WeChat Developer Tools: WeChat Developer Tools installed (download from official site)

Step 1: WeChat Official Account Platform Setup​

1.1 Access WeChat Official Account Platform​

  1. Navigate to the WeChat Official Account Platform
  2. Log in with your WeChat account credentials
  3. Scan the QR code with your WeChat mobile app to complete authentication
Account Types

Different account types have different capabilities:

  • 订阅号 (Subscription Account): Basic features, limited API access
  • 服务号 (Service Account): Full API access, payment integration
  • 企业号 (Enterprise Account): Enterprise features, advanced APIs

1.2 Configure Basic Account Information​

  1. Navigate to Settings (设置) > Account Information (账号信息)
  2. Complete the following configurations:
    • Account Name (账号名称): Your official account display name
    • Account ID (微信号): Unique identifier for your account
    • Account Type (账号类型): Verify your account type and capabilities
    • Verification Status (认证状态): Check if account is verified (认证)
Verification

For production deployments, account verification (认证) is highly recommended as it provides:

  • Access to advanced APIs
  • Payment integration capabilities
  • Higher API rate limits
  • Enhanced security features

1.3 Configure Server Domain​

  1. Navigate to Settings (设置) > Development Settings (开发设置)

  2. Configure the following:

    Server Domain (服务器域名):

    • Request Domain (request 合法域名): Your API server domain (e.g., https://api.example.com)
    • Socket Domain (socket 合法域名): WebSocket server domain (if applicable)
    • Upload Domain (uploadFile 合法域名): File upload server domain
    • Download Domain (downloadFile 合法域名): File download server domain
    Domain Requirements
    • Domains must use HTTPS (SSL certificate required)
    • Domains must be publicly accessible
    • IP addresses are not allowed
    • Port numbers should not be included (use standard 443 for HTTPS)

1.4 Configure Business Domain​

  1. Navigate to Settings (设置) > Business Domain (业务域名)
  2. Add your business domain(s) that will be used in web-view components
  3. Download the verification file and place it on your web server

1.5 Enable Developer Mode​

  1. Navigate to Development (开发) > Development Settings (开发管理)

  2. Click Enable (启用) to activate developer mode

  3. Configure the following:

    Server Configuration (服务器配置):

    • URL (服务器地址): Your server callback URL (e.g., https://api.example.com/wechat/callback)
    • Token (令牌): A secure token for message verification (generate a strong random string)
    • EncodingAESKey (消息加解密密钥): Auto-generated encryption key (save this securely)
    • Message Encryption (消息加解密方式): Choose encryption mode
      • Plain Mode (明文模式): For development/testing
      • Compatible Mode (兼容模式): Supports both encrypted and plain messages
      • Safe Mode (安全模式): Full encryption (recommended for production)
Security
  • Store the Token and EncodingAESKey securely
  • Never commit these values to version control
  • Use environment variables or secret management systems

1.6 Configure Mini Program Settings​

  1. Navigate to Mini Program (小程序) > Settings (设置)

  2. Configure the following:

    Basic Information (基本信息):

    • AppID (小程序 ID): Unique identifier for your Mini Program (save this)
    • AppSecret (小程序密钥): Secret key for API authentication (save this securely)
    • Mini Program Name (小程序名称): Display name
    • Logo (头像): Upload your Mini Program logo
    • Introduction (简介): Brief description

    Server Domain (服务器域名):

    • Configure the same domains as in Step 1.3

    Business Domain (业务域名):

    • Configure web-view domains if needed
AppID and AppSecret
  • AppID: Public identifier, can be included in client-side code
  • AppSecret: Must be kept secret, only use on server-side
  • Regenerate AppSecret if compromised

Step 2: WeChat Developer Tools Setup​

2.1 Download and Install​

  1. Download WeChat Developer Tools from the official website
  2. Install the application following the installation wizard
  3. Launch WeChat Developer Tools

2.2 Initial Configuration​

  1. Login: Log in with your WeChat account (scan QR code)
  2. Create Project: Click + to create a new project
  3. Project Configuration:
    • Project Name: Enter your project name
    • Directory: Select your project directory
    • AppID: Enter your Mini Program AppID (from Step 1.6)
    • Development Mode: Select appropriate mode
      • Mini Program: Standard Mini Program development
      • Cloud Development: If using WeChat Cloud services

2.3 Configure Project Settings​

  1. Open Project Settings (项目设置) in Developer Tools

  2. Configure the following:

    Local Settings (本地设置):

    • Do not verify valid domain names (不校验合法域名): Enable for local development
    • Do not verify TLS version (不校验 TLS 版本): Enable for local development
    • Do not verify HTTPS certificates (不校验 HTTPS 证书): Enable for local development
    Development vs Production

    These settings should only be enabled for local development. In production, all validations must pass.

Step 3: Project Configuration​

3.1 Environment Variables Setup​

Create environment configuration files for different environments:

.env.development (for local development):

# WeChat Configuration
WECHAT_APPID=your_appid_here
WECHAT_APPSECRET=your_appsecret_here
WECHAT_TOKEN=your_token_here
WECHAT_ENCODING_AES_KEY=your_encoding_aes_key_here

# API Configuration
API_BASE_URL=https://api-dev.example.com

.env.production (for production):

# WeChat Configuration
WECHAT_APPID=your_production_appid
WECHAT_APPSECRET=your_production_appsecret
WECHAT_TOKEN=your_production_token
WECHAT_ENCODING_AES_KEY=your_production_encoding_aes_key

# API Configuration
API_BASE_URL=https://api.example.com
Security
  • Never commit .env.production to version control
  • Add .env.* to .gitignore
  • Use GitHub Secrets or similar for CI/CD pipelines

3.2 Configure app.json​

Configure the main Mini Program configuration file:

{
  "pages": ["pages/index/index", "pages/profile/profile"],
  "window": {
    "navigationBarTitleText": "SBM CRM Platform",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "image/icon_component.png",
        "selectedIconPath": "image/icon_component_HL.png",
        "text": "Home"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "permission": {
    "scope.userLocation": {
      "desc": "Your location will be used for location-based services"
    }
  }
}

3.3 Configure project.config.json​

Configure project-specific settings:

{
  "description": "SBM CRM Platform WeChat Mini Program",
  "packOptions": {
    "ignore": [
      {
        "type": "file",
        "value": ".eslintrc.js"
      }
    ]
  },
  "setting": {
    "urlCheck": true,
    "es6": true,
    "enhance": true,
    "postcss": true,
    "minified": true
  },
  "compileType": "miniprogram",
  "libVersion": "2.19.4",
  "appid": "your_appid_here",
  "projectname": "sbm-crm-miniprogram",
  "condition": {}
}

Step 4: GitHub Repository Configuration​

4.1 Configure Secret Environments​

  1. Navigate to your GitHub repository

  2. Go to Settings > Environments

  3. Create or update environments (e.g., staging, production)

  4. Add the following secrets:

    WeChat Configuration Secrets:

    • WECHAT_APPID: Your Mini Program AppID
    • WECHAT_APPSECRET: Your Mini Program AppSecret
    • WECHAT_TOKEN: Server configuration token
    • WECHAT_ENCODING_AES_KEY: Message encryption key

    API Configuration Secrets:

    • API_BASE_URL: Base URL for API requests
    • API_KEY: API authentication key (if required)
Secret Management

Store all sensitive credentials in GitHub Secrets. Never hardcode them in your source code.

4.2 Configure CI/CD Pipeline​

Ensure your CI/CD pipeline (GitHub Actions) is configured to:

  • Use the correct environment secrets
  • Build the Mini Program with production settings
  • Upload to WeChat platform (if automated)

Step 5: Verify Setup​

5.1 Test Local Development​

  1. Open your project in WeChat Developer Tools
  2. Click Compile (编译) to build the project
  3. Test basic functionality:
    • Navigation between pages
    • API requests to your backend
    • WeChat API calls (if implemented)

5.2 Test Server Configuration​

  1. Send a test message or event to your server callback URL
  2. Verify your server correctly processes WeChat messages
  3. Check server logs for any errors

5.3 Verify Domain Configuration​

  1. Test API requests from the Mini Program
  2. Verify all configured domains are accessible
  3. Check for any domain validation errors in Developer Tools console

5.4 Test Upload Process​

  1. Click Upload (上传) in Developer Tools
  2. Fill in version information:
    • Version Number: e.g., 1.0.0
    • Project Notes: Description of changes
  3. Verify upload completes successfully

Troubleshooting​

Common Issues​

Cannot access WeChat Official Account Platform

  • Verify your WeChat account has admin/developer permissions
  • Check if the account is properly verified
  • Ensure you're using the correct login credentials

Domain validation fails

  • Verify SSL certificate is valid and properly configured
  • Ensure domain is publicly accessible (not behind firewall)
  • Check that verification file is correctly placed on server
  • Verify domain uses HTTPS (not HTTP)

AppSecret not working

  • Verify AppSecret is correctly copied (no extra spaces)
  • Check if AppSecret was regenerated (old one becomes invalid)
  • Ensure AppSecret is used only on server-side

API requests fail

  • Verify server domain is correctly configured in WeChat platform
  • Check API server is running and accessible
  • Verify SSL certificate is valid
  • Check network timeout settings in app.json

Developer Tools connection issues

  • Verify you're logged in with the correct WeChat account
  • Check if your account has permission to access the Mini Program
  • Try logging out and logging back in

Build/compile errors

  • Check project.config.json configuration
  • Verify all required dependencies are installed
  • Review error messages in Developer Tools console
  • Ensure Node.js version is compatible

Next Steps​

After completing the initial setup:

  1. Develop Your Mini Program: Start building features using WeChat Mini Program APIs
  2. Test Thoroughly: Use Developer Tools and trial versions for testing
  3. Deploy to Production: Follow the WeChat Deployment Guide for deployment
  4. Monitor Performance: Use WeChat platform analytics to monitor usage
  5. Iterate and Improve: Gather user feedback and continuously improve

Additional Resources​