uni-app + Vue3 + Vite + uView Plus 全流程搭建指南（TS/微信小程序）

核心目标：基于精简后的 package.json，搭建可直接开发微信小程序的跨端项目，适配 TS 语法与 uView Plus UI 库。

一、环境准备（前置必做）

安装 Node.js：下载 Node.js 18+ 稳定版（推荐 18.19.0），安装后终端执行 node -v 和 npm -v 验证是否成功。
安装开发工具：
- 代码编辑器：VS Code（安装 Vue Language Features、TypeScript、SCSS 插件）。
- 小程序工具：微信开发者工具（开启「服务端口」：设置 → 安全设置 → 服务端口勾选）。
全局安装 uni-app CLI（可选，提升创建效率）：
bash 复制代码
```
npm install -g @dcloudio/uni-cli
```

二、项目创建（基于 Vite 模板）

终端切换到目标目录，执行命令创建项目（wechat-mp-project 为项目名，可自定义）：
bash 复制代码
```
npx degit dcloudio/uni-preset-vue#vite wechat-mp-project
```
进入项目目录：
bash 复制代码
```
cd wechat-mp-project
```

三、配置 package.json（核心精简版）

替换项目根目录的 package.json 为以下内容（已适配 TS + 微信小程序，无冗余依赖）：

json 复制代码

{
  "name": "uni-preset-vue",
  "version": "0.0.0",
  "scripts": {
    "dev:mp-weixin": "uni -p mp-weixin",
    "build:mp-weixin": "uni build -p mp-weixin"
  },
  "dependencies": {
    "@dcloudio/uni-app": "3.0.0-4080420251103001",
    "@dcloudio/uni-components": "3.0.0-4080420251103001",
    "@dcloudio/uni-mp-weixin": "3.0.0-4080420251103001",
    "vue": "^3.4.21",
    "uview-plus": "^3.6.18",
    "pinia": "^2.1.7"
  },
  "devDependencies": {
    "@dcloudio/types": "^3.4.8",
    "@dcloudio/vite-plugin-uni": "3.0.0-4080420251103001",
    "sass": "1.63.2",
    "vite": "5.2.8",
    "typescript": "^5.4.5"
  }
}

四、安装依赖（清理旧依赖 + 全新安装）

清理残留依赖（避免版本冲突）：

Windows 系统：

bash 复制代码

rd /s /q node_modules
del package-lock.json
del yarn.lock

Mac/Linux 系统：

bash 复制代码

rm -rf node_modules
rm -f package-lock.json
rm -f yarn.lock

安装新依赖（根据精简后的 package.json 下载）：
bash 复制代码
```
npm install
```
验证安装：若终端无报错，且项目根目录出现 node_modules 文件夹，说明安装成功。

五、uView Plus 配置（全局引入 + 样式适配）

1. 引入 uView Plus 主文件

在 main.ts 中全局引入 uView Plus（Vue3 组合式 API 写法）：

typescript 复制代码

import { createSSRApp } from 'vue'
import App from './App.vue'
// 引入 uView Plus
import uView from 'uview-plus'
// 引入 uView Plus 全局样式
import 'uview-plus/index.scss'

export function createApp() {
  const app = createSSRApp(App)
  app.use(uView) // 注册 uView 组件
  return {
    app
  }
}

2. 配置 SCSS 全局变量（可选）

在项目根目录创建 uni.scss 文件，引入 uView 全局样式变量（用于自定义主题）：

scss 复制代码

// 引入 uView Plus 全局变量
@import "uview-plus/theme.scss";
// 可自定义主题变量（覆盖默认值）
$u-primary: #2979ff; // 主色调改为蓝色
$u-border-radius: 8px; // 全局圆角

3. 配置 pages.json（确保组件按需加载）

在 pages.json 中添加 uView 组件按需加载配置（无需手动引入组件）：

json 复制代码

{
  "easycom": {
		"autoscan": true,
		"custom": {
			"^u-(.*)": "uview-x/components/u-$1/u-$1.uvue"
		}
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "WeChat",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

六、TS 配置（确保语法校验正常）

项目根目录创建 tsconfig.json（TS 编译配置）：

json 复制代码

{
  "compilerOptions": {
    "target": "ESNext",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "lib": ["ESNext", "DOM"],
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "types": [
      "@dcloudio/types",
      "uview-plus/typings"
    ]
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

七、Pinia 状态管理配置（可选，全局状态用）

在 src 目录下创建 store/index.ts：

typescript 复制代码

import { createPinia } from 'pinia'
const pinia = createPinia()
export default pinia

在 main.ts 中引入 Pinia：

typescript 复制代码

import { createSSRApp } from 'vue'
import App from './App.vue'
import uViewPlus from 'uview-plus'
import 'uview-plus/index.scss'
import pinia from './store' // 引入 Pinia

export function createApp() {
  const app = createSSRApp(App)
  app.use(uViewPlus)
  app.use(pinia) // 注册 Pinia
  return {
    app
  }
}

八、项目启动与预览（微信小程序）

启动开发服务器（热更新）：

bash 复制代码

npm run dev:mp-weixin

预览项目：
- 终端输出 编译成功 后，会在 dist/dev/mp-weixin 生成微信小程序代码。
- 打开微信开发者工具，点击「导入项目」，选择 dist/dev/mp-weixin 目录，即可看到项目预览效果。

九、测试 uView Plus 组件（验证配置）

修改 pages/index/index.vue，添加 uView 组件测试是否生效：

vue 复制代码

<template>
  <view class="container">
    <u-button type="primary" @click="handleClick">测试 uView 按钮</u-button>
    <u-card title="测试卡片" sub-title="uView Plus 组件正常加载" margin="20rpx 0"></u-card>
  </view>
</template>

<script setup lang="ts">
const handleClick = () => {
  uni.showToast({ title: 'uView 组件生效！' })
}
</script>

<style scoped lang="scss">
.container {
  padding: 20rpx;
}
</style>

保存后，微信开发者工具会自动刷新，若能看到按钮和卡片组件，且点击按钮弹出提示，说明配置全部生效。

十、项目打包（发布微信小程序）

执行打包命令：

bash 复制代码

npm run build:mp-weixin

打包完成后，项目根目录会生成 dist/build/mp-weixin 目录。
微信开发者工具中，选择该目录，点击「上传」，即可提交小程序代码审核。