一、uni-app项目创建与运行指南（Vue3 ）

最新推荐文章于 2026-08-20 20:48:23 发布

原创最新推荐文章于 2026-08-20 20:48:23 发布 · 176 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

一、项目创建

1. 创建项目

本节使用 uni-app 官方提供的 Vue3 + Vite 模板快速初始化项目，避免手动搭建脚手架。

环境准备：Node.js 16.0 及以上版本，推荐使用最新长期支持版本；并提前安装微信开发者工具。

在终端执行以下命令创建项目：

npx degit dcloudio/uni-preset-vue#vite my-vue3-project

命令说明：

npx degit：直接下载 GitHub 仓库模板，无需全局安装脚手架工具；
dcloudio/uni-preset-vue#vite：uni-app 官方 Vue3 + Vite 模板；
my-vue3-project：项目目录名，可按需修改。

创建完成后，进入项目目录：

cd my-vue3-project

2. 安装依赖

进入项目目录后，安装模板依赖：

npm install

如果依赖下载较慢，可切换到国内镜像：
npm install --registry=https://registry.npmmirror.com

3. 项目打包

依赖安装完成后，启动微信小程序的开发模式编译：

npm run dev:mp-weixin

该命令会持续监听文件变化，并编译到 dist/dev/mp-weixin 目录，后续导入微信开发者工具进行调试。

二、项目运行

1. 导入项目

编译完成后，打开微信开发者工具，选择「导入项目」，路径选择项目根目录下的 dist/dev/mp-weixin 目录：

导入小程序项目

填写小程序AppID与后端服务

导入时需要填写项目信息：

AppID：填写自己的小程序 AppID；没有 AppID 可先选择「测试号」体验本地功能；
后端服务：本地预览可直接选择「不使用云服务」；

小程序 AppID 可在微信公众平台注册小程序后获取；后端服务仅在需要使用云开发能力时才需选择。

2. 小程序效果预览

导入成功并开启编译后，即可在微信开发者工具中查看小程序运行效果：

小程序效果预览

三、项目结构

my-uniapp-project/
├── .husky/                 # Git Hooks 工具配置，用于在提交代码前自动执行代码检查
├── public/                 # 纯静态公共资源（不参与 Vite 构建，直接复制到 dist）
├── src/                    # 📦 核心源码目录（所有业务代码均在此开发）
│   ├── api/                # 【接口请求层】统一管理所有与后端的 HTTP 通信
│   │   ├── request.ts      # 核心：封装 uni.request，实现请求/响应拦截器、Token注入、统一错误处理
│   │   └── modules/        # 按业务模块拆分 API 定义（如 user.ts, order.ts），保持代码高内聚
│   │
│   ├── assets/             # 【需编译的静态资源】存放会被 Vite 构建处理的资源
│   │   ├── images/         # 需要被压缩、转换或作为模块导入的图片
│   │   └── styles/         # 全局 SCSS/Less 变量、Mixin、基础重置样式等
│   │
│   ├── components/         # 【全局通用组件】存放不含业务逻辑的纯 UI 组件（项目 UI 库基石）
│   │   ├── base/           # 基础组件（如 BaseButton, AppModal, FormInput）
│   │   └── business/       # 跨模块复用的业务组件（如 UserAvatar, StatusTag）
│   │
│   ├── composables/        # 【组合式函数/Hooks】Vue3 精髓，封装和复用带状态的逻辑
│   │   ├── usePagination.ts# 示例：封装列表分页逻辑（当前页、下一页、数据加载状态等）
│   │   └── useAuth.ts      # 示例：封装用户登录态、Token 获取逻辑
│   │
│   ├── layouts/            # 【全局布局组件】存放应用的骨架结构（如自定义导航栏、底部 TabBar）
│   │
│   ├── pages/              # 【主包页面】存放核心、启动时必须加载的页面（如首页、登录页、TabBar页）
│   │   ├── index/          # 首页模块
│   │   │   └── index.vue   
│   │   └── login/          # 登录模块
│   │       └── login.vue   
│   │
│   ├── packages/           # 【业务分包】大型项目的灵魂，按业务领域划分的独立分包
│   │   ├── user-center/    # 用户中心分包（高内聚，包含自己的 pages, components, apis）
│   │   └── order/          # 订单模块分包（极大降低主包体积和模块间耦合度）
│   │
│   ├── static/             # 【免编译静态资源】uni-app 约定目录，文件原封不动复制到最终包
│   │   ├── icons/          # 适合存放小程序图标、字体文件等（注意：不要放未使用的废文件）
│   │   └── tabbar/         # TabBar 专用图标
│   │
│   ├── store/              # 【全局状态管理】使用 Pinia，按模块化方式组织
│   │   ├── modules/        # 业务状态模块（如 user.ts, cart.ts）
│   │   └── index.ts        # 统一注册并导出所有 Store 模块
│   │
│   ├── utils/              # 【通用工具函数】存放无副作用的纯函数工具集
│   │   ├── format.ts       # 日期格式化、金额处理等
│   │   └── validate.ts     # 表单数据校验规则
│   │
│   ├── App.vue             # 应用入口：配置 App 全局样式、监听应用级生命周期
│   ├── main.ts             # Vue 初始化入口文件：挂载 Pinia、全局组件等
│   ├── manifest.json       # 应用配置：配置 AppID、启动页、权限、微信小程序特有配置等
│   ├── pages.json          # 📄 【页面路由配置】见下方详细解析
│   └── uni.scss            # 内置的常用样式变量（uni-app 官方提供，可全局直接使用）
│
├── index.html              # H5 平台的入口 HTML 模板文件
├── package.json            # 项目依赖管理与运行脚本配置
├── tsconfig.json           # 📄 【TS 编译器配置】见下方详细解析
├── vite.config.ts          # 📄 【Vite 构建配置】见下方详细解析
├── commitlint.config.js    # Commitizen 提交信息规范配置，确保 Git 提交记录标准化
└── README.md               # 项目说明文档

标签

#uni-app