# vue3-taro-app-template

**Repository Path**: donymh/vue3-taro-app-template

## Basic Information

- **Project Name**: vue3-taro-app-template
- **Description**: vue3+webpack+taro+NutUI+pinia实现的简单实用的跨端小程序开发模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-28
- **Last Updated**: 2025-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: template, TARO, vue3, webpack5, nutui

## README

# vue3-taro-app-template

## 介绍
vue3+webpack+taro+NutUI+pinia实现的简单实用的跨端小程序开发模板

## 软件架构
该项目是一个基于 Vue 3、Taro 和 NutUI 的跨端小程序开发模板，采用模块化设计，支持多端构建。以下是项目的软件架构概述：
### 技术栈
- 前端框架: Vue 3
- 构建工具: Webpack 5
- 状态管理: Pinia
- UI 组件库: NutUI（适用于小程序）
- 代码规范: ESLint, StyleLint
- 版本控制: Git（包含 pre-commit 钩子）
### 目录结构说明
```
vue3-taro-app-template/
├── src/                    # 源码目录
│   ├── app.config.ts       # 小程序配置文件（页面路径、分包等）
│   ├── app.scss            # 全局样式文件
│   ├── main.ts             # 应用入口文件
│   ├── pages/              # 页面组件目录
│   │   └── index/          # 示例首页
│   │       └── index.vue   # 首页视图
│   │   └── pay-record/     # 支付记录页
│   │       └── index.vue   # 支付记录视图
│   ├── subpackage/         # 分包目录
│   │   └── record-detail/  # 记录详情页
│   │       └── index.vue   # 记录详情视图
│   │   └── order-detail/   # 订单详情页
│   │       └── index.vue   # 订单详情视图
│   ├── stores/             # Pinia 状态管理模块
│   ├── hooks/              # 自定义 Hook 函数
│   ├── components/         # 公共组件
│   ├── constants/          # 全局项目常量
│   ├── assets/             # 静态资源（图片、字体等）
│   ├── styles/             # 样式文件（SCSS 变量等）
│   └── utils/              # 工具函数
├── config/                 # Taro 构建配置文件
│   ├── dev.ts              # 开发环境配置
│   └── prod.ts             # 生产环境配置
│   └── index.ts            # 主配置文件
├── public/                 # 静态资源（不经过构建处理）
├── .eslintrc.cjs           # eslint 配置文件
├── .stylelintrc.cjs        # stylelint 配置文件
├── .commitlintrc.cjs       # commitlint 配置文件
├── babel.config.js         #  babel 配置文件
├── README.md               # 项目说明文档
├── package.json            # 项目依赖与脚本配置
└── tsconfig.json           
```

## 快速开始

### 安装教程
```bash
git clone https://gitee.com/donymh/vue3-taro-app-template.git
```
或者使用cli工具 [hive-create-app](https://dony.online/usage/cli.html) 下载。
### 安装依赖
```bash
cd vue3-taro-app-template

pnpm install
```
### 启动项目
```bash
pnpm run dev:weapp
# 或指定其他平台，如 h5、rn
pnpm run dev:h5
```
### 构建生产版本
```bash
pnpm run build:weapp
# 或构建其他平台
pnpm run build:h5
```
### 开发规范
- 页面开发：在 src/pages/ 目录下创建新页面，遵循 Vue 3 的单文件组件结构。
- 分包机制：项目已配置分包，大型应用应合理划分 subpackage 以提升加载速度。
- 状态管理：使用 Pinia 创建 Store，并在组件中通过 useStore() 引入。
- 样式管理：全局样式定义在 src/app.scss 中，可使用 SCSS 变量进行主题定制。
- 代码规范：项目集成 ESLint 和 StyleLint，提交代码前会自动校验格式。

## 模板开发说明
详见 [template usage](https://dony.online/usage)

## eslint,stylelint,pre-commit
详见 [template usage 指引](https://dony.online/usage/guide/eslint.html)

## 小程序分包配置
```src/app.config.ts
export default {
  pages: [
    'pages/index/index',
    'pages/pay-record/index'
  ],
  window: {
    backgroundTextStyle: 'light',
    navigationBarBackgroundColor: '#fff',
    navigationBarTitleText: 'WeChat',
    navigationBarTextStyle: 'black'
  },
  subpackages: [
    {
      root: 'subpackage',
      pages: [
        'record-detail/index',
        'order-detail/index'
      ]
    }
  ],
};
```

## 数据状态管理 pinia
1. 安装pinia
2. 创建stores
3. .在main.js中引入pinia

## 模式和环境变量
详见 官方文档 [模式和环境变量](https://docs.taro.zone/docs/env-mode-config)
* 注意事项：如果你使用的是webpack5，请确保你的webpack配置中包含了` process polyfill`，否则可能会导致在业务代码中无法使用`process`的一些问题。
```
...
webpackChain(chain) {
  chain.resolve.plugin('tsconfig-paths').use(TsconfigPathsPlugin);
  chain.plugin('unplugin-vue-components').use(Components({
    resolvers: [NutUIResolver({ taro: true })]
  }));

  
  // 添加 process polyfill 解决在业务代码中使用 process 报错 process is not defined 的问题
  // eslint-disable-next-line @typescript-eslint/no-require-imports
  chain.plugin('providePlugin').use(require('webpack').ProvidePlugin, [
    {
      process: 'process/browser.js',
    },
  ]);
}
...
```


## 封装样式
小程序中不支持 `<style scoped>`，推荐使用 cssModules 代替，示例如/pages/index/index.vue中的使用形式。

## 注意事项
- 小程序中不支持 `<style scoped>`，推荐使用 cssModules 代替。
- 不能在页面组件的 DOM 树之外插入元素，因此不支持 `<teleport>`。
- 在 H5 端使用 ref 获取基础组件的 DOM 节点，现在只能得到适配层的 Vue 组件实例，而不是对应的 webComponent 根节点。在 Vue2 里可以通过修改父元素的 refs 属性实现，但 Vue3 中组件间初始化顺序有变化，因此暂时不能支持。
- 小程序端非类似 HTML 表单标签规范的表单组件，如 Picker，暂不兼容 v-model。Vue3 的 v-model 绑定属性改为了 modelValue，事件绑定改为了 update:modelValue。对于 HTML 表单标签会自动对接表单的值与事件，例如 input 会自动对应 modelValue 与 value、update:modelValue 与 @input。但对于 Picker 这种小程序特有表单则无法对应，建议这种情况不使用 v-model。
- 所有组件的 id 必须在整个应用中保持唯一（即使他们在不同的页面），否则可能导致事件不触发的问题