跳转到内容
VPT

快速开始

本指南使用 create-vite-taro 创建一个同时支持微信、支付宝、抖音小程序和 Web 的应用。默认模板已经配置好 Vite 8、React 19、Taro 4、TypeScript 和 Tailwind CSS v4。

准备工作

Section titled “准备工作”
  • Node.js 24 或更高版本。
  • pnpm、npm 或 yarn。推荐使用 pnpm。
  • 安装微信开发者工具和/或支付宝/抖音小程序开发者工具最新版。
  • 对应平台的小程序 App ID。没有微信 App ID 时也可以先使用测试号体验部分功能。

1. 创建项目

Section titled “1. 创建项目”
终端窗口
pnpm --config.minimum-release-age=0 create vite-taro@latest my-app
cd my-app
pnpm install
pnpm approve-builds

2. 配置小程序 App ID

Section titled “2. 配置小程序 App ID”

创建工具会在 .env.local 中生成占位值。开发自己的小程序前，请替换当前平台的真实值：

VITE_VPT_WECHAT_APP_ID=wx1234567890abcdef
VITE_VPT_ALIPAY_APP_ID=2021000000000000
VITE_VPT_TIKTOK_APP_ID=testAppId

.env.local 已被 Git 忽略，不会提交到仓库。

3. 运行开发模式

Section titled “3. 运行开发模式”

按目标选择一个命令，启动 Vite 开发模式热更新：

终端窗口
pnpm dev:wx         # 微信小程序
pnpm dev:zfb        # 支付宝小程序
pnpm dev:tt         # 抖音小程序
pnpm dev:h5         # Web 应用
  • 小程序： 等待 Vite 完成初始构建，然后在对应平台的开发者工具中导入生成目录：微信 dist/wx、支付宝 dist/zfb、抖音 dist/tt。不要打开项目源码根目录。
  • Web： 在浏览器中访问终端显示的地址。

如需同时开发多个目标，请在不同终端中分别运行对应命令。

自动重新构建（--watch）

Section titled “自动重新构建（--watch）”

如果不需要热更新，例如让 AI 批量修改代码，可以使用：

终端窗口
pnpm build:wx --watch        # 微信小程序
pnpm build:zfb --watch       # 支付宝小程序
pnpm build:tt --watch        # 抖音小程序

这些命令运行 vite build --watch，在源码变化后重新生成对应 dist/... 下的生产构建。

不要与 dev:... 同时运行，以免同时写入输出目录。

4. 编辑第一个页面

Section titled “4. 编辑第一个页面”

模板的默认首页组件位于 src/pages/home/index.tsx。可以直接使用 div、span、button 等 HTML 标签编写 React 组件；vpt 在小程序端将支持的标签映射为原生组件：

import Taro from 'virtual:taro/api'
import { useState } from 'react'


function HomePage() {
    const [count, setCount] = useState(0)


    return (
        <div className="flex min-h-screen flex-col gap-4 p-6">
            <span className="text-2xl font-bold">你好，VPT</span>
            <span>计数：{count}</span>
            <button type="button" onClick={() => setCount((currentCount) => currentCount + 1)}>增加</button>
            <button type="button" onClick={() => Taro.showToast({ title: '来自 Taro' })}>显示提示</button>
        </div>
    )
}


export default HomePage

HTML 标签可以与 ScrollView 等 Taro 组件混用。

导入用途
virtual:taro/componentsView、Text、Button、Image、ScrollView 等 Taro React 组件。
virtual:taro/apiTaro.navigateTo、Taro.getWindowInfo、Taro.useLaunch 等 API 和 hooks。
virtual:taro/native为当前小程序目标声明带类型的原生组件属性和事件。

5. 构建与检查

Section titled “5. 构建与检查”
终端窗口
pnpm build:wx        # 构建微信小程序到 dist/wx
pnpm build:zfb       # 构建支付宝小程序到 dist/zfb
pnpm build:tt        # 构建抖音小程序到 dist/tt
pnpm build:h5        # 构建 Web 应用到 dist/h5
pnpm preview:h5      # 预览 Web 生产构建
pnpm typecheck       # 使用 tsc 检查类型

每次 Vite 运行只构建一个目标：

目标开发脚本生产构建脚本输出目录
微信小程序（wx）dev:wxbuild:wxdist/wx
支付宝小程序（zfb）dev:zfbbuild:zfbdist/zfb
抖音小程序（tt）dev:ttbuild:ttdist/tt
Web（h5）dev:h5build:h5dist/h5

6. 了解项目结构

Section titled “6. 了解项目结构”

项目的核心文件如下：

my-app/
├── .env.local
├── index.html
├── package.json
├── vite.config.ts
└── src/
    ├── app.css
    ├── app.tsx
    ├── components/
    └── pages/
        └── home/
            └── index.tsx
  • vite.config.ts 标准 vite 项目的配置文件。
  • src/app.tsx 是应用入口。
  • src/app.css 包含全局样式和 Tailwind CSS v4 配置。
  • src/pages/home/index.tsx 是默认首页组件。

常见问题

Section titled “常见问题”

小程序开发者工具无法打开项目

Section titled “小程序开发者工具无法打开项目”

确认导入的是当前目标的 dist/wx、dist/zfb 或 dist/tt，并检查 .env.local 中对应的 App ID 是否属于当前开发者账号。

Tailwind 工具类没有生效

Section titled “Tailwind 工具类没有生效”

确认 src/app.css 仍包含 Tailwind 的三个导入和源码扫描配置：

@import "tailwindcss/theme.css";
@import "tailwindcss/preflight.css";
@import "tailwindcss/utilities.css";


@source "./";

移动源码文件或修改扫描范围后，请重新启动开发服务器。

pnpm 忽略了依赖构建脚本

Section titled “pnpm 忽略了依赖构建脚本”

运行 pnpm approve-builds，按提示批准需要执行构建脚本的依赖，然后重新安装。

下一步

Section titled “下一步”