WeChat Mini Program Cloud Server SDK

Common errors

• Error: Cannot find module 'wx-server-sdk'

  cause The `wx-server-sdk` package has not been installed in the specific Cloud Function's `node_modules` directory.
  fix Navigate into the `cloudfunctions/<your-function-name>` directory and run `npm install --save wx-server-sdk`.

• TypeError: Cannot read properties of undefined (reading 'database')

  cause The `cloud.init()` method was not called or failed, meaning the `cloud` object was not properly initialized before attempting to access its properties like `database`.
  fix Add `cloud.init({ env: 'your-environment-id' });` at the beginning of your Cloud Function's `main` function.

• Error: 'collection' must be a string

  cause The `collection()` method of the database was called without providing a valid string for the collection name.
  fix Ensure `db.collection('your_collection_name')` passes a non-empty string as the collection identifier.

• SyntaxError: 'await' is only valid in async functions and the top level bodies of modules

  cause Using `await` inside a Cloud Function without declaring the function `async`.
  fix Declare your Cloud Function's entry point `export async function main(event: any, context: any) { ... }`.

Warnings

• breaking Version 3.0.1 introduced a breaking change regarding BigInt serialization. Native `JSON.stringify` will serialize the SDK's built-in `BigInt` (implemented via `bigint.js`) as a string, not a number, potentially impacting existing code expecting numeric `BigInt` values in JSON output.
  Fix: Review any code that serializes BigInt values from database queries or other SDK operations to JSON. Adjust parsing logic to handle BigInts as strings or use custom serialization/deserialization logic if numeric representation is strictly required. For example, convert BigInt to `Number()` if within safe integer limits before JSON.stringify.
• gotcha Cloud Functions run in a Node.js environment and are granted unrestricted read/write access to Cloud Database and Cloud Storage by default. This powerful access model requires careful security consideration to prevent data breaches or unintended modifications.
  Fix: Implement robust access control policies (ACLs) at the database collection level, use database security rules, and strictly validate all incoming data and user permissions within your Cloud Functions. Never trust client-side input directly.
• gotcha The `wx-server-sdk` must be installed within the specific Cloud Function's directory, not just at the project root level. Failing to do so will result in 'Cannot find module' errors at runtime.
  Fix: Navigate to your Cloud Function's directory (e.g., `cloudfunctions/myFunction`) and run `npm install --save wx-server-sdk@latest`. Ensure each function requiring the SDK has its own `node_modules` with the dependency.
• gotcha The `cloud.init()` method must be called exactly once at the entry point of your Cloud Function before any other cloud operations are performed. Forgetting this will lead to errors when attempting to use database, storage, or other cloud APIs.
  Fix: Ensure `cloud.init()` is the first cloud-related call in your Cloud Function's `main` entry point, ideally configuring the `env` parameter with your Cloud Development environment ID (e.g., `cloud.init({ env: 'your-env-id' })`).

Install

• npm install wx-server-sdk npm
• yarn add wx-server-sdk yarn
• pnpm add wx-server-sdk pnpm

Imports

• cloud
  wrong:

  import { cloud } from 'wx-server-sdk';

  correct:

  import cloud from 'wx-server-sdk';

  The primary `cloud` object is typically imported as a default export or through `import * as cloud from 'wx-server-sdk;'` for full module access. CommonJS `require` pattern also returns the full `cloud` object.
• init
  wrong:

  const { init } = require('wx-server-sdk'); init();

  correct:

  import cloud from 'wx-server-sdk'; cloud.init({ env: 'your-env-id' });

  The `init` function is a method of the main `cloud` object and must be called after importing `cloud`.
• DB.command
  wrong:

  import { command } from 'wx-server-sdk';

  correct:

  import cloud from 'wx-server-sdk'; const db = cloud.database(); const _ = db.command;

  Database commands (`db.command`) are accessed via the `db` instance obtained from `cloud.database()`, not directly from the SDK root.
• Cloud

  import * as Cloud from 'wx-server-sdk'; // Use Cloud.init(), Cloud.database(), etc.

  This pattern provides full access to all exported members of the SDK under the `Cloud` namespace, suitable for TypeScript environments or when a single named import is insufficient.

Quickstart

This quickstart demonstrates initializing the SDK, performing basic database operations (add and query), and invoking another Cloud Function within a WeChat Cloud Function. It highlights best practices for error handling and accessing user context.

import cloud from 'wx-server-sdk';

// Initialize the cloud environment
cloud.init({
  env: process.env.WX_CLOUD_ENV_ID ?? '', // Ensure environment ID is configured
  traceUser: true, // Enable user tracking for logging
});

const db = cloud.database();
const _ = db.command;

// Cloud Function entry point
export async function main(event: any, context: any) {
  try {
    // Example: Add a new record to a 'todos' collection
    const addResult = await db.collection('todos').add({
      data: {
        description: 'Learn wx-server-sdk',
        completed: false,
        createdDate: new Date(),
        _openid: event.userInfo.openId, // Automatically available in Cloud Function event
      },
    });
    console.log('Added todo:', addResult);

    // Example: Query records from 'todos' collection
    const queryResult = await db.collection('todos')
      .where({
        _openid: event.userInfo.openId,
        completed: false,
      })
      .orderBy('createdDate', 'desc')
      .limit(10)
      .get();
    console.log('Queried todos:', queryResult.data);

    // Example: Call another Cloud Function (replace 'anotherFunction' with actual function name)
    const callFunctionResult = await cloud.callFunction({
      name: 'anotherFunction',
      data: { message: 'Hello from main function' },
    });
    console.log('Called another function:', callFunctionResult.result);

    return {
      statusCode: 200,
      body: 'Operation successful',
      addResult,
      queryResult: queryResult.data,
      callFunctionResult: callFunctionResult.result
    };
  } catch (e: any) {
    console.error('Operation failed:', e);
    return {
      statusCode: 500,
      body: `Operation failed: ${e.message}`,
    };
  }
}