你好，我是 Kagol，个人公众号：前端开源星球。

本指南提供了 TinyVue 的全面安装说明，TinyVue 是一个企业级 UI 组件库，支持使用同一套代码库同时兼容 Vue 2 和 Vue 3。无论你是启动新项目还是将 TinyVue 集成到现有应用中，本指南都将通过清晰、分步的说明带你完成安装过程。

系统要求

在安装 TinyVue 之前，请确保你的开发环境满足以下要求：

要求	版本	用途
Node.js	>= 18.0.0	JavaScript 运行环境
pnpm	>= 9.5.0	用于工作区管理的包管理器
Vue	2.x 或 3.x	前端框架

由于 TinyVue 采用带有工作区依赖的 monorepo 结构，因此要求使用 pnpm 作为包管理器。代码库包含一个预安装钩子，会自动强制执行此要求。

安装概述

无论使用哪个 Vue 版本，安装过程都遵循一致的模式。

安装方法

方法 1：NPM 包安装

对于 Vue 3 项目

TinyVue 为 Vue 3 应用提供了专用包：

npm install @opentiny/vue@3

对于 Vue 2 项目

对于 Vue 2 应用，请安装 Vue 2 版本：

npm install @opentiny/vue@2

两个包共享相同的组件 API，确保了兼容性，使版本间的迁移变得简单直接。

方法 2：开发环境搭建

如果你想贡献代码或在本地探索该库，请克隆代码库并搭建开发环境：

git clone git@github.com:opentiny/tiny-vue.git
cd tiny-vue
 
# 使用 pnpm 安装依赖
pnpm install
 
# 启动 Vue 3 开发服务器
pnpm dev
 
# 或启动 Vue 2 开发服务器
pnpm dev2

Vue 3 开发服务器运行在 7130 端口，而 Vue 2 运行在 7126 端口。

按组件安装

TinyVue 支持全包导入和可 tree-shaking 的单个组件导入。包结构包含 104+ 个组件，以独立工作区包的形式组织，以优化打包体积。

核心组件包

@opentiny/vue 包导出所有组件：

组件类别	示例
数据展示	Card, Table, Calendar, Carousel
表单组件	Input, Select, DatePicker, ColorPicker
导航	Breadcrumb, Menu, Tabs, Steps
反馈	Alert, Dialog, Drawer, Loading
其他	Button, Layout, Grid

主题包

提供两种主题包：

主题包	描述	使用场景
@opentiny/vue-theme	默认 Aurora 主题	标准企业应用
@opentiny/vue-theme-saas	SaaS 专用主题	SaaS 平台应用

Vue 3 集成

步骤 1：安装依赖

npm install @opentiny/vue@3

步骤 2：配置 main.ts

创建或更新你的 src/main.ts 文件：

import * as Vue3 from 'vue'
import { createI18n } from 'vue-i18n'
import { initI18n } from '@opentiny/vue-locale'
import { Loading } from '@opentiny/vue'
import App from './App.vue'
 
const app = Vue3.createApp(App)
 
// 初始化 i18n
app.use(initI18n({ createI18n, i18n: {} } as any))
 
// 注册全局组件
app.use(Loading)
 
// 挂载应用
app.mount('#app')

 

步骤 3：在应用中使用组件

在 src/App.vue 中：

<script setup lang="ts">
  import { Button as TinyButton } from '@opentiny/vue'
</script>
 
<template>
  <tiny-button>Tiny Vue</tiny-button>
</template>

 

Vue 2 集成

步骤 1：安装依赖

npm install @opentiny/vue@2

步骤 2：配置 main.ts

创建或更新你的 src/main.ts 文件：

import Vue from 'vue'
import VueI18n from 'vue-i18n'
import { initI18n } from '@opentiny/vue-locale'
import { Loading } from '@opentiny/vue'
import App from './App.vue'
 
Vue.config.productionTip = false
 
// 初始化 i18n
Vue.use(VueI18n)
 
// 注册全局组件
Vue.use(Loading)
 
new Vue({
  i18n: initI18n({ VueI18n, i18n: {} } as any),
  render: (h) => h(App)
}).$mount('#app')

 

步骤 3：在应用中使用组件

组件使用方式与 Vue 3 相同：

<script>
  import { Button as TinyButton } from '@opentiny/vue'
  
  export default {
    components: {
      TinyButton
    }
  }
</script>
 
<template>
  <tiny-button>Tiny Vue</tiny-button>
</template>

 

模式和主题配置

OpenTiny Vue 支持 PC 和移动端模式，可以动态配置：

模式检测

Vue 2 和 Vue 3 示例都使用基于 URL 的模式检测：

// Vue 3 示例
const mode = location.pathname.split('/')[1] || 'pc'
 
app.config.globalProperties.tiny_mode = { value: mode }
app.config.globalProperties.isPcMode = mode === 'pc'
app.config.globalProperties.isMobileMode = mode === 'mobile'

// Vue 2 示例
const mode = location.pathname.split('/')[1] || 'pc'
 
Vue.prototype.tiny_mode = { value: mode }
Vue.prototype.isPcMode = mode === 'pc'
Vue.prototype.isMobileMode = mode === 'mobile'

 

主题变量注入

为支持 SaaS 主题，注入主题变量：

// Vue 3
app.config.globalProperties.tiny_theme = { 
  value: import.meta.env.VITE_TINY_THEME 
}
 
// Vue 2
Vue.prototype.tiny_theme = { 
  value: import.meta.env.VITE_TINY_THEME 
}

 

安装对比

方面	Vue 3	Vue 2
包名	@opentiny/vue@3	@opentiny/vue@2
API 兼容性	Composition API + Options API	Options API（通过插件支持 Composition API）
i18n 集成	vue-i18n + @opentiny/vue-locale	vue-i18n + @opentiny/vue-locale
应用初始化	Vue3.createApp()	new Vue()
全局属性	app.config.globalProperties	Vue.prototype
开发服务器端口	7130	7126

Vue 2 和 Vue 3 集成的主要区别在于应用初始化模式。所有组件 API 保持完全相同，确保版本间的平滑迁移。

验证

安装完成后，请验证你的设置：

1. 检查安装：运行 npm list @opentiny/vue 确认安装
2. 导入测试：在 IDE 中尝试导入组件以验证路径
3. 组件渲染：使用 Button 等简单组件测试渲染
4. 开发服务器：启动开发服务器并检查控制台错误

 

故障排除

问题	解决方案
找不到包	确保使用 npm 8+ 且包标签正确（@3 或 @2）
导入错误	验证你的 Vue 版本与已安装的包匹配
主题未生效	确保在入口文件中导入了主题 CSS
i18n 错误	检查在初始化前是否已安装 vue-i18n

联系我们

GitHub：https://github.com/opentiny/tiny-vue（欢迎 Star ⭐）

官网：https://opentiny.design/tiny-vue

个人博客：kagol.com.cn

小助手微信：opentiny-official

公众号：OpenTiny