Taro+Vue3+TS+Vite 小程序开发底座搭建流程

结合 taro-ui-vue3 官方文档（https://b2nil.github.io/taro-ui-vue3/docs/quickstart.html），用豆包梳理了 Taro+Vue3+TS+Vite+Taro UI Vue3 小程序完整开发底座搭建流程：

一、前置环境准备（文档要求+基础依赖）

# 1. 检查 Node 版本（文档要求 ≥16.0.0，推荐 16/18 LTS）
node -v
# 2. 全局安装 Taro CLI（文档要求 Taro ≥3.6，需匹配 taro-ui-vue3 版本）
npm install -g @tarojs/cli@^3.6.0
# 3. 验证 Taro 版本（确保 ≥3.6.0）
taro -v

二、步骤1：初始化 Taro+Vue3+TS+Vite 项目（文档适配版）

# 1. 初始化项目（命名为 wx-mini-vue3-base）
taro init wx-mini-vue3-base

# 2. 交互式选择配置（严格按文档适配 Taro UI Vue3）：
# ? 请选择框架：Vue3
# ? 请选择 TS：Yes（文档推荐 TS 开发）
# ? 请选择 CSS 预处理器：SCSS（Taro UI Vue3 基于 SCSS 开发）
# ? 请选择编译工具：Vite（文档优先推荐 Vite）
# ? 请选择模板：默认模板
# ? 请选择包管理器：npm（文档示例用 npm，pnpm 需额外配置）

三、步骤2：安装 Taro UI Vue3（文档核心步骤）

进入项目目录，按文档要求安装适配版本的 Taro UI Vue3：

cd wx-mini-vue3-base
# 安装 taro-ui-vue3（文档推荐最新稳定版）
npm install taro-ui-vue3@latest --save
# 安装类型声明（TS 开发必备，文档补充）
npm install @types/wechat-miniprogram --save-dev

四、步骤3：配置 Taro UI Vue3（文档规范）

1. 全局引入（推荐，文档优先方案）

修改 src/app.ts（项目入口文件），全局注册 Taro UI Vue3 组件：

import { createApp } from 'vue'
import App from './App.vue'
// 1. 导入 Taro UI Vue3 组件库
import TaroUiVue3 from 'taro-ui-vue3'
// 2. 导入组件库样式（文档必加，否则样式失效）
import 'taro-ui-vue3/dist/style/index.scss'

const app = createApp(App)
// 3. 全局注册组件库
app.use(TaroUiVue3)

export default app

2. 按需引入（文档可选方案，减小体积）

若无需全局引入，可按文档示例在组件内按需导入：

<!-- src/pages/index/index.vue -->
<template>
  <AtButton type="primary">按钮</AtButton>
</template>

<script setup lang="ts">
// 按需导入组件+样式（文档规范）
import { AtButton } from 'taro-ui-vue3'
import 'taro-ui-vue3/dist/style/at-button.scss'
</script>

五、步骤4：配置小程序核心能力（文档+工程化增强）

1. 修改 Taro 配置（config/index.js）

按文档要求开启小程序 v2 运行时，适配 Taro UI Vue3 渲染：

module.exports = {
  projectName: 'wx-mini-vue3-base',
  designWidth: 750, // 文档默认设计稿宽度
  deviceRatio: { 750: 1 },
  sourceRoot: 'src',
  outputRoot: `dist/${process.env.TARO_ENV}`,
  framework: 'vue3',
  compiler: 'vite', // 匹配文档推荐的 Vite 编译
  cache: { enable: true },
  mini: {
    runtime: { enable: true }, // 文档推荐开启 v2 运行时（提升渲染性能）
    optimizeMainPackage: { enable: true },
    postcss: {
      pxtransform: { enable: true }, // Taro UI Vue3 依赖 px 转 rpx
      url: { enable: true, config: { limit: 1024 } },
      // 文档补充：适配 Taro UI Vue3 的 CSS 解析
      cssModules: { enable: false }
    }
  },
  // 环境变量（文档未提，工程化增强）
  defineConstants: {
    VITE_BASE_API: process.env.NODE_ENV === 'development' 
      ? '"https://dev-api.xxx.com"' 
      : '"https://prod-api.xxx.com"'
  },
  // 文档关键：添加 Vite 别名（避免 Taro UI Vue3 路径解析错误）
  vite: {
    alias: {
      '@': '/src'
    }
  }
}

2. 新增环境变量文件（工程化增强，非文档必加）

# .env.development（根目录）
NODE_ENV=development
VITE_BASE_API=https://dev-api.xxx.com

# .env.production（根目录）
NODE_ENV=production
VITE_BASE_API=https://prod-api.xxx.com

六、步骤5：补充进阶能力（文档未提，企业级必备）

按文档生态补充路由/请求/Pinia/错误处理（兼容 Taro UI Vue3）：

1. 安装 Pinia（状态管理）

npm install pinia --save

2. 完整工具文件（路由/请求/错误处理）

// src/store/index.ts（Pinia 入口）
import { createPinia } from 'pinia'
const pinia = createPinia()
export default pinia

// src/store/modules/user.ts（用户状态示例）
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', {
  state: () => ({ token: '', userName: '' }),
  actions: {
    setToken(newToken: string) {
      this.token = newToken
      uni.setStorageSync('token', newToken)
    }
  }
})

// src/utils/router.ts（路由封装）
import { navigateTo, redirectTo, switchTab, reLaunch } from '@tarojs/taro'
import type { RouteOption } from '@tarojs/taro/types/index'

export const router = {
  push: (options: RouteOption) => {
    const token = uni.getStorageSync('token')
    if (!token && options.url !== '/pages/login/index') {
      return navigateTo({ url: '/pages/login/index' })
    }
    return navigateTo(options)
  },
  replace: redirectTo,
  switchTab: switchTab,
  reLaunch: reLaunch
}

// src/utils/request.ts（请求封装）
import { request } from '@tarojs/taro'
import type { RequestOption } from '@tarojs/taro/types/index'
import { router } from './router'

const requestInterceptor = (options: RequestOption) => {
  const token = uni.getStorageSync('token')
  if (token) {
    options.header = { ...options.header, 'Authorization': `Bearer ${token}` }
  }
  options.url = import.meta.env.VITE_BASE_API + options.url
  return options
}

const responseInterceptor = (res: any) => {
  if (res.statusCode !== 200) {
    uni.showToast({ title: '请求失败', icon: 'none' })
    return Promise.reject(res)
  }
  if (res.data.code === 401) {
    uni.removeStorageSync('token')
    router.push({ url: '/pages/login/index' })
    return Promise.reject(res)
  }
  return res.data
}

export const http = <T = any>(options: RequestOption): Promise<T> => {
  return new Promise((resolve, reject) => {
    request({
      ...requestInterceptor(options),
      success: (res) => resolve(responseInterceptor(res)),
      fail: (err) => reject(err)
    })
  })
}

// src/utils/errorHandler.ts（错误处理）
import { showToast } from '@tarojs/taro'

export const errorHandler = (err: any, type: 'api' | 'page' | 'mini') => {
  switch (type) {
    case 'api':
      showToast({ title: err.msg || '接口请求失败', icon: 'none' })
      break
    case 'page':
      console.error('页面错误：', err)
      showToast({ title: '页面加载失败', icon: 'none' })
      break
    case 'mini':
      console.error('小程序原生错误：', err)
      showToast({ title: '系统错误，请重试', icon: 'none' })
      break
  }
}

3. 挂载 Pinia（修改 src/app.ts）

import { createApp } from 'vue'
import App from './App.vue'
import TaroUiVue3 from 'taro-ui-vue3'
import 'taro-ui-vue3/dist/style/index.scss'
// 导入 Pinia
import pinia from './store'

const app = createApp(App)
app.use(TaroUiVue3)
app.use(pinia) // 挂载 Pinia

export default app

七、步骤6：测试 Taro UI Vue3 组件（文档示例）

修改 src/pages/index/index.vue，验证组件是否正常渲染：

<template>
  <view class="index-container">
    <!-- Taro UI Vue3 按钮组件（文档示例） -->
    <AtButton type="primary" @click="handleClick">主按钮</AtButton>
    <AtButton type="secondary" style="margin-top: 10px;">次按钮</AtButton>
    <!-- Taro UI Vue3 表单组件 -->
    <AtInput 
      placeholder="请输入内容" 
      v-model="inputVal" 
      style="margin-top: 10px;"
    />
    <!-- 状态展示 -->
    <text class="token" style="margin-top: 10px; display: block;">
      Token：{{ userStore.token }}
    </text>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useUserStore } from '@/store/modules/user'
import { http } from '@/utils/request'
import { router } from '@/utils/router'
import { errorHandler } from '@/utils/errorHandler'

// 响应式数据
const inputVal = ref('')
const userStore = useUserStore()

// 事件处理
const handleClick = async () => {
  try {
    // 测试状态管理
    userStore.setToken('taro-ui-vue3-token-2025')
    // 测试请求（替换为实际接口）
    const res = await http({ url: '/user/info', method: 'GET' })
    console.log('请求成功：', res)
  } catch (err) {
    errorHandler(err, 'api')
  }
}
</script>

<style lang="scss" scoped>
.index-container {
  padding: 30px;
}
.token {
  font-size: 24rpx;
  color: #666;
}
</style>

八、步骤7：启动调试（文档标准流程）

# 启动微信小程序开发服务（热更新）
npm run dev:weapp

操作步骤（文档要求）：

1. 打开微信开发者工具；
2. 导入项目根目录下的 dist/weapp 文件夹；
3. 勾选「不校验合法域名、web-view（业务域名）等」；
4. 确认组件正常渲染、点击事件生效。

九、步骤8：生产打包（文档规范）

# 打包生产环境代码（文档推荐）
npm run build:weapp

打包完成后，dist/weapp 目录为可上传的小程序代码包，按微信官方流程提交审核即可。

十、文档关键注意事项（避坑指南）

1. 版本兼容：Taro CLI 版本必须 ≥3.6.0，否则 Taro UI Vue3 会渲染异常（文档明确要求）；
2. 样式导入 ：必须手动导入 taro-ui-vue3/dist/style/index.scss，否则组件无样式（文档核心提醒）；
3. Vite 配置 ：需添加 alias: { '@': '/src' }，避免 Taro UI Vue3 组件路径解析错误；
4. 小程序基础库：微信开发者工具中需将基础库版本切换至 ≥2.30.0（文档推荐）；
5. TS 类型 ：若提示组件类型错误，需安装 @types/taro-ui-vue3（文档补充方案）。

最终目录结构（文档适配版）

wx-mini-vue3-base/
├── config/
│   └── index.js           # Taro 核心配置（适配 Taro UI Vue3）
├── src/
│   ├── pages/             # 业务页面（含 Taro UI Vue3 组件示例）
│   ├── components/        # 全局组件
│   ├── utils/             # 路由/请求/错误处理
│   ├── store/             # Pinia 状态管理
│   ├── app.vue            # 根组件
│   └── app.ts             # 入口文件（注册 Taro UI Vue3 + Pinia）
├── .env.development       # 开发环境变量
├── .env.production        # 生产环境变量
└── package.json           # 依赖（含 taro-ui-vue3）

注意

微信开发者工具无法直接运行 Taro 源码，必须先通过 npm 命令将 Taro+Vue3 代码编译为小程序原生代码，再导入微信开发者工具运行。