TypeScript 类型与微信小游戏类型声明

预计阅读 25 分钟

📋版本信息

最后更新：2026-07-09 · 适用基础库：≥ 3.9.0（最低兼容 ≥ 2.30.0）· TypeScript 5.7+（项目依赖）/ 7.0 RC（最新）

微信小游戏 API 以 JavaScript 为原生接口语言，但生产项目普遍使用 TypeScript。本章讲解如何为项目引入微信小游戏类型声明、wx 全局命名空间的正确用法，以及与 Cocos Creator / Unity / LayaAir 等引擎类型共存时的常见陷阱。

---

为什么需要专门的类型声明

前端工程师熟悉的 @types/node、@types/react 等包，为运行环境提供了类型签名。微信小游戏同样存在官方类型声明 @types/wechat-minigame，它定义了：

• 全局 wx 对象及其所有 API
• WechatMinigame 命名空间下的接口与回调类型
• Canvas、Image、GameRecorder 等平台特有对象

没有这些声明时，TypeScript 会把 wx 识别为 any，失去类型检查、自动补全和重构能力。

---

安装与配置

1. 安装类型声明

# 原生 Canvas / 自定义框架项目
pnpm add -D @types/wechat-minigame

# 若使用 Cocos Creator，其内置类型通常已包含微信小游戏接口，无需额外安装

2. 在 tsconfig.json 中启用

{
  "compilerOptions": {
    "types": ["wechat-minigame"]
  }
}

💡与 @types/node 共存

若项目同时需要 Node.js 类型（如构建脚本），不要把 wechat-minigame 和 node 同时放进 types 数组，否则可能产生全局冲突（例如两者都声明 setTimeout 的返回类型）。推荐方案：

1. 源代码目录使用 types: ["wechat-minigame"]。
2. 构建脚本目录单独使用 types: ["node"]，通过项目引用（project references）隔离。

---

wx 全局命名空间核心类型

引入声明后，最常用的是 WechatMinigame 命名空间。以下是几个典型示例：

// 登录结果
async function login(): Promise<WechatMinigame.LoginSuccessCallbackResult> {
  return new Promise((resolve, reject) => {
    wx.login({ success: resolve, fail: reject })
  })
}

// 用户信息（敏感接口，新版基础库已收紧权限）
interface UserProfile {
  nickName: string
  avatarUrl: string
}

// 网络请求
async function fetchScore(openid: string): Promise<any> {
  const res = await wxRequest<{ score: number }>({
    url: 'https://your-server.com/api/score',
    data: { openid },
  })
  return res.data
}

常见回调类型速查

API	成功回调类型	失败回调类型
wx.login	LoginSuccessCallbackResult	GeneralCallbackResult
wx.request	RequestSuccessCallbackResult	GeneralCallbackResult
wx.getSystemInfoSync	SystemInfo	—
wx.createInnerAudioContext	InnerAudioContext	—
wx.createRewardedVideoAd	RewardedVideoAd	—

---

与引擎类型共存

Cocos Creator 3.x

Cocos Creator 3.x 使用自己的 cc 模块类型。在脚本中同时引用 cc 和 WechatMinigame 很常见：

import { _decorator, Component } from 'cc'

const { ccclass } = _decorator

@ccclass('WxBridge')
export class WxBridge extends Component {
  private ad: WechatMinigame.RewardedVideoAd | null = null

  onLoad() {
    if (typeof wx === 'undefined') return
    this.ad = wx.createRewardedVideoAd({ adUnitId: 'your-ad-unit-id' })
  }
}

LayaAir

LayaAir 的全局对象是 Laya，与 wx 不冲突。但在 Laya 脚本中使用 wx 时，仍需确保 tsconfig.json 引入了 wechat-minigame 类型。

Unity (WX-WASM-SDK)

Unity 微信小游戏使用 C# 开发，类型系统完全不同。WX-WASM-SDK 会提供 C# 层的 WX 类封装，与 JavaScript 的 wx 是桥接关系，不需要 wechat-minigame 类型。

---

类型安全最佳实践

1. 避免滥用 any

// ❌ 不推荐
function handleResult(res: any) {
  const data = res.data
}

// ✅ 推荐
interface ApiResponse<T> {
  code: number
  data: T
  message: string
}

function handleResult<T>(res: WechatMinigame.RequestSuccessCallbackResult) {
  const json = res.data as ApiResponse<T>
  return json.data
}

2. 为自定义事件加类型

// 定义游戏内事件映射
interface GameEvents {
  scoreChanged: { score: number }
  gameOver: { finalScore: number; bestScore: number }
}

type EventName = keyof GameEvents

class TypedEventBus {
  private listeners: Partial<Record<EventName, Array<(data: any) => void>>> = {}

  on<K extends EventName>(event: K, handler: (data: GameEvents[K]) => void) {
    if (!this.listeners[event]) this.listeners[event] = []
    this.listeners[event]!.push(handler)
  }

  emit<K extends EventName>(event: K, data: GameEvents[K]) {
    this.listeners[event]?.forEach((h) => h(data))
  }
}

3. 运行时类型守卫

TypeScript 类型只在编译期有效。对于服务端返回的数据，应配合运行时校验：

import { z } from 'zod'

const ScoreSchema = z.object({
  openid: z.string(),
  score: z.number(),
  updateTime: z.number(),
})

async function getScore(openid: string) {
  const res = await wxRequest({ url: `/api/score/${openid}` })
  return ScoreSchema.parse(res.data) // 运行时校验 + 推导为正确类型
}

---

常见类型陷阱

问题	原因	解决
wx is not defined	在 Web 预览环境运行小游戏代码	使用 typeof wx !== 'undefined' 守卫
Cannot find name 'wx'	未安装或未启用 @types/wechat-minigame	安装并加入 tsconfig.json
setTimeout 返回类型冲突	node 与 wechat-minigame 同时存在	项目引用隔离或移除其中一个
RequestSuccessCallbackResult.data 为 any	微信 API 返回数据不确定	用泛型或 zod 做运行时转换
引擎类型与 wx 类型冲突	引擎也声明了全局 wx	检查引擎版本，必要时使用 skipLibCheck

---

📝 课后练习

练习 1：为 wx.request 编写泛型封装

题目： 编写一个类型安全的 wxRequest<T> 函数，要求：

1. 接收 url、method、data 等参数。
2. 返回 Promise<T>。
3. 在 fail 时 reject 错误对象。

参考答案：

function wxRequest<T = unknown>(
  options: Omit<WechatMinigame.RequestOption, 'success' | 'fail'>
): Promise<T> {
  return new Promise((resolve, reject) => {
    wx.request({
      ...options,
      success: (res) => resolve(res.data as T),
      fail: reject,
    })
  })
}

---

本章小结

• 使用 @types/wechat-minigame 获得完整的 wx API 类型提示。
• 注意与 Node.js 类型的全局冲突，推荐项目引用隔离。
• 避免滥用 any，结合泛型和运行时校验（如 zod）保证数据安全。
• Cocos/LayaAir/Unity 与微信小游戏类型的共存方式各不相同，需按引擎调整配置。