vite-plugin-uni-cloudfunctions

v0.1.1

Published

a month ago

Vite plugin that compiles TypeScript WeChat cloud functions into self-contained deploy units and syncs them to the mp-weixin output directory, enabling uni-app cloud function development without HBuilderX. 在纯 Vite 工作流（如 unh）中开发 uni-app 微信小程序云函数。

vite-plugin-uni-cloudfunctions

A Vite plugin for building and syncing WeChat Mini Program cloud functions (微信云函数) in uni-app projects — develop TypeScript cloud functions in a pure Vite workflow, no HBuilderX required.

在使用 unh（uni-helper CLI）等纯 Vite 工作流开发 uni-app 微信小程序时，脱离 HBuilderX 也能顺畅开发微信云函数：本插件将 TypeScript 云函数编译为自包含的独立部署单元，并自动同步到微信小程序输出目录。

背景

用 Vite CLI（如 unh）开发 uni-app 微信小程序时，前端产物由 Vite 输出到 dist/{dev,build}/mp-weixin，但微信云函数没有对应的构建链路：TypeScript 源码无法直接部署，手动编译再拷贝到输出目录既繁琐又容易漏。本插件把云函数纳入同一个 Vite 生命周期——开发期由 dev server watcher 触发增量构建，生产期由构建流程直接发布产物，之后在微信开发者工具里即可正常上传部署云函数。

安装

pnpm add -D vite-plugin-uni-cloudfunctions

环境要求：

| 依赖 | 版本 | | --- | --- | | Node.js | ^22.18.0 \|\| >=24.11.0 | | Vite（peer dependency） | ^5.2.8 |

vite 是 peer dependency，运行时始终使用消费项目安装的 Vite 实例，不会打包出第二份 Vite 或破坏 plugin lifecycle。

Skills 安装

本仓库附带一组 Agent Skills，用于在 Claude Code / Codex 等 AI 编码助手中获得微信云函数开发的最佳实践支持。使用 skills CLI 一键安装：

npx skills add JsonLee12138/vite-plugin-uni-cloudfunctions

执行后按提示选择需要的 skill：

| Skill | 说明 | | --- | --- | | wx-cloudfunctions | 微信云函数开发工作流：新增/修改云函数、action 分层、zod 校验、单测、基于本插件的打包构建 | | cloudbase | 腾讯云开发（CloudBase/TCB）全套开发指南：数据库、云函数、云存储、身份认证、内置 AI 等 | | wechatide-skill | 微信开发者工具自动化：预览、上传、调试、日志排查与云环境操作 | | zod | Zod schema 校验最佳实践，配合云函数入参校验使用 |

使用方案

快速开始

在 vite.config.ts 注册插件即可，开发与生产共用同一份配置：

import { defineConfig } from 'vite';
import { uniCloudFunctions } from 'vite-plugin-uni-cloudfunctions';

export default defineConfig({
  plugins: [uniCloudFunctions()],
});

自定义源码目录和不打包进单文件的依赖：

uniCloudFunctions({
  functionsDir: 'server-functions',
  external: ['wx-server-sdk'],
});

插件仅在 UNI_PLATFORM=mp-weixin 时生效：

开发期：pnpm dev:mp-weixin（或 unh wx）启动后，首次全量同步云函数到 dist/dev/mp-weixin/cloudfunctions/，后续源码 add/change/unlink 触发增量构建。
生产期：pnpm build:mp-weixin 构建时自动编译并发布到 dist/build/mp-weixin/cloudfunctions/，无需额外命令。

pnpm build:mp-weixin
test -f dist/build/mp-weixin/cloudfunctions/promptApi/index.js

注意：UNI_PLATFORM 未设置时插件会抛出 E_PLATFORM_MISSING；设置为其他平台（如 h5）时插件静默禁用。插件运行时会在项目根创建 .vite-plugin-uni-cloudfunctions/ 临时目录，请将其加入 .gitignore。

生产构建中，同一 Rollup 构建周期的多个输出共用一次生成，后续 watch 周期会重新生成。

参数

| Option | Default | Description | | --- | --- | --- | | projectRoot | Vite resolved root | 云函数项目根目录。 | | functionsDir | cloudfunctions | 相对 projectRoot 的源码目录。 | | external | ['wx-server-sdk'] | 只允许 bare package name；这些依赖不打进函数单文件。 |

包同时导出 UniCloudFunctionsOptions、ResolvedCloudFunctionsConfig 类型与 CloudFunctionsError 错误类（含 code / phase 字段），便于在自定义脚本中做类型安全的错误处理。

TypeScript 项目配置

在项目根目录新建 tsconfig.cloudfunctions.json，让云函数使用独立于 uni-app 前端的编译配置：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"],
    "strict": true,
    "noEmit": true
  },
  "include": ["cloudfunctions/**/*.ts"]
}

根 tsconfig.json 使用 project references：

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.cloudfunctions.json" }
  ]
}

若云函数目录不是默认的 cloudfunctions（例如 server-functions），把 include 改为 ["server-functions/**/*.ts"]。

随后可以独立检查云函数：

pnpm exec tsc -p tsconfig.cloudfunctions.json --noEmit

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vite-plugin-uni-cloudfunctions

目录

背景

安装

Skills 安装

使用方案

快速开始

参数

TypeScript 项目配置

License