开始使用
本指南将帮助您创建第一个 VUP 项目并让它在本地运行。
前置要求
在开始之前，请确保您已安装以下工具：
- Node.js (版本 22.0.0 或更高)
- pnpm (版本 10.0.0 或更高)
安装 Node.js
推荐使用 nvm (Node Version Manager) 来管理 Node.js 版本：
bash
# 安装 nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 安装 Node.js 22
nvm install 22
nvm use 22
# Windows 用户可以使用 nvm-windows
# 下载地址：https://github.com/coreybutler/nvm-windows/releases或者直接从 Node.js 官网 下载安装。
安装 pnpm
bash
# 使用 npm 安装
npm install -g pnpm
# 或使用 Homebrew (macOS)
brew install pnpm
# 或使用独立安装脚本
curl -fsSL https://get.pnpm.io/install.sh | sh -验证安装
您可以通过以下命令检查版本：
bash
node --version # 应该显示 v22.x.x 或更高
pnpm --version # 应该显示 10.x.x 或更高安装 VUP CLI
推荐方式：使用 npx（无需全局安装）
bash
# 直接使用，无需安装
npx vup-cli --version
npx vup-cli init my-project全局安装
bash
# 使用 npm
npm install -g vup-cli
# 使用 pnpm
pnpm add -g vup-cli
# 使用 yarn
yarn global add vup-cli验证安装
bash
# 如果使用 npx
npx vup-cli --version
# 如果全局安装成功
vup --version安装问题排查
如果全局安装后 vup 命令无法使用，可以尝试以下解决方案：
方案1：使用 npx（推荐）
bash
# 直接使用 npx，无需全局安装
npx vup-cli init my-project
npx vup-cli add my-app方案2：重新安装
bash
# 卸载后重新安装
npm uninstall -g vup-cli
npm install -g vup-cli
# 或者使用 pnpm
pnpm remove -g vup-cli
pnpm add -g vup-cli注意： 最新版本在安装时会自动创建 bin 链接。如果仍然遇到问题，使用
npx是最可靠的方法。
创建新项目
1. 初始化项目
bash
# 使用 npx（推荐）
npx vup-cli init my-project
# 或使用全局安装的命令
vup init my-project这将创建一个空的 Monorepo 项目结构。
2. 进入项目目录
bash
cd my-project3. 添加应用
bash
# 使用 npx（推荐）
npx vup-cli add my-app
# 或使用全局安装的命令
vup add my-app这将提示您选择需要的模板类型：
- Vue SPA
- Qiankun
- Nuxt.js
- VitePress
- Nest.js
- UniApp
- Capacitor
- WXT
- Electron
- Components
- CLI
4. 安装依赖
bash
pnpm install5. 添加功能包（可选）
如果需要使用功能包，可以使用 vup use 命令：
bash
# 使用 npx（推荐）
npx vup-cli use my-package
# 或使用全局安装的命令
vup use my-package系统会提示您选择功能包类型：
- @vup/ui - UI 组件库
- @vup/iconfont - Iconfont 图标组件
- @vup/richeditor - 富文本编辑器
- @vup/nest-upload - NestJS 上传模块
6. 启动开发服务器
bash
# 启动所有应用
pnpm dev:all
# 或启动特定应用
pnpm --filter <应用名称> dev
# 例如：启动 Vue 应用
pnpm --filter my-vue-app dev开发服务器将启动，具体端口号会在终端中显示。预置的端口（示例）：
- Vue 应用：
http://localhost:9301 - NestJS API：
http://localhost:9310
项目结构
VUP 采用 Monorepo 架构，创建项目后的结构如下：
初始项目结构
bash
vup init my-project创建后的基础结构：
my-project/
├── apps/ # 应用目录（初始为空）
├── _shared/ # 共享资源
│ ├── assets/ # 共享静态资源
│ └── styles/ # 共享样式
├── .github/ # GitHub 配置
├── .husky/ # Git hooks 配置
├── .vercel/ # Vercel 配置
├── .vscode/ # VSCode 配置
├── package.json # 根项目配置
├── pnpm-workspace.yaml # pnpm 工作区配置
├── tsconfig.json # TypeScript 配置
├── tailwind.config.js # Tailwind 配置
├── eslint.config.js # ESLint 配置
├── prettier.config.js # Prettier 配置
├── postcss.config.js # PostCSS 配置
├── vercel.json # Vercel 部署配置
├── CHANGELOG.md # 更新日志
└── README.md # 项目说明添加应用后的结构
bash
vup add my-vue-app # 添加应用，系统会提示选择模板类型
vup add my-api # 添加应用，系统会提示选择模板类型添加应用后的结构：
my-project/
├── apps/ # 应用目录
│ ├── my-vue-app/ # Vue SPA 应用
│ └── my-api/ # Nest.js 后端
├── _shared/ # 共享资源
│ ├── assets/ # 共享静态资源
│ └── styles/ # 共享样式
└── 配置文件...开发工作流
日常开发
1. 启动开发服务器
bash
# 启动特定应用
pnpm --filter <应用名称> dev
# 例如
pnpm --filter my-vue-app dev启动开发服务器，支持热重载（HMR）。
2. 代码检查
bash
# 检查特定应用的代码
pnpm --filter <应用名称> lint
# 自动修复 ESLint 错误
pnpm --filter <应用名称> lint:fix
# 检查所有应用
pnpm lint:all
# 修复所有应用
pnpm lint:fix3. 代码格式化
bash
# 格式化特定应用
pnpm --filter <应用名称> format
# 检查格式化
pnpm --filter <应用名称> format:check
# 格式化所有应用
pnpm format:all
# 检查所有应用格式化
pnpm format:check4. 类型检查
bash
# TypeScript 类型检查
pnpm --filter <应用名称> type-check
# 检查所有应用
pnpm type-check5. 构建项目
bash
# 构建特定应用
pnpm --filter <应用名称> build
# 构建所有应用
pnpm build:all构建的文件通常输出到 .output 或 dist 目录（具体取决于模板类型）。
6. 预览生产构建
bash
# 预览特定应用
pnpm --filter <应用名称> preview本地预览生产构建。
批量操作
VUP 提供了批量操作命令，方便同时管理多个应用：
bash
# 启动所有应用
pnpm dev:all
# 构建所有应用
pnpm build:all
# 检查所有应用代码
pnpm lint:all
# 格式化所有应用代码
pnpm format:all
# 类型检查所有应用
pnpm type-check环境变量配置
创建环境变量文件
bash
# 复制示例文件
cp .env.example .env.localVite 环境变量规则
- 客户端变量：必须以
VITE_开头 - 服务端变量：可以任意命名（如
NODE_ENV）
变量优先级（从高到低）
.env.local（本地环境，不提交到 Git）.env.development（开发环境）.env.production（生产环境）.env（通用环境）
常用配置示例
bash
# .env.local
VITE_APP_TITLE=我的应用
VITE_APP_DESCRIPTION=应用描述
VITE_API_BASE_URL=http://localhost:3000
VITE_ENABLE_MOCK=true
VITE_ENABLE_DEVTOOLS=true添加应用到现有项目
如果您已经有一个项目，可以添加新的应用：
bash
# 使用 npx（推荐）
npx vup-cli add my-app
npx vup-cli add my-app --path /custom/path
npx vup-cli add my-app --force
# 或使用全局安装的命令
vup add my-app
vup add my-app --path /custom/path
vup add my-app --force命令选项
--path <path>- 指定项目路径（默认为当前目录）--force- 强制覆盖已存在的应用
添加功能包到现有项目
bash
# 使用 npx（推荐）
npx vup-cli use my-package
npx vup-cli use my-package --path /custom/path
npx vup-cli use my-package --force
# 或使用全局安装的命令
vup use my-package
vup use my-package --path /custom/path
vup use my-package --force功能包会被添加到 packages/ 目录下。
模板管理
查看可用模板
bash
# 使用 npx
npx vup-cli template --list
# 或使用全局安装的命令
vup template --list更新模板
bash
# 使用 npx
npx vup-cli template --update
# 或使用全局安装的命令
vup template --update移除模板
bash
# 使用 npx
npx vup-cli template --remove
# 或使用全局安装的命令
vup template --remove语言设置
查看当前语言
bash
# 使用 npx
npx vup-cli language --current
# 或使用全局安装的命令
vup language --current重置语言设置
bash
# 使用 npx
npx vup-cli language --reset
# 或使用全局安装的命令
vup language --reset常见问题
端口冲突
如果默认端口被占用，可以在应用的配置文件中修改端口号：
typescript
// vite.config.js
export default defineConfig({
server: {
port: 9302, // 修改为其他端口
},
});依赖安装失败
如果遇到依赖安装问题，可以尝试：
bash
# 清除缓存
pnpm store prune
# 删除 node_modules 和 lock 文件后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install模板下载失败
如果模板下载失败，可以手动更新模板：
bash
vup template --updateWindows 路径问题
在 Windows 上如果遇到路径相关问题，确保使用正确的路径分隔符，或使用 Git Bash 或 WSL。
下一步
现在您已经成功创建了第一个 VUP 项目，接下来可以：
- 📖 了解 VUP 是什么 - 深入了解 VUP 的核心理念和特性
- 🎯 探索模板文档 - 了解不同项目类型的详细使用方法
- 📦 查看功能包文档 - 了解如何使用可复用的功能包
- 🎨 学习主题系统 - 了解如何配置和使用主题
- 🛠️ 配置开发工具 - 提高开发效率和代码质量
- 🚀 设置部署方案 - 了解如何部署您的应用
- 📝 管理版本和日志 - 使用 release-it 管理版本发布