开始使用
开始使用 本指南将帮助您创建第一个 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 -验证安装 您可以通过以下命令检查版本：
bashnode --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. 进入项目目录 bashcd my-project3. 添加应用 bash# 使用 npx（推荐）
npx vup-cli add my-app
# 或使用全局安装的命令
vup add my-app这将提示您选择需要的模板类型：
Vue SPAQiankunNuxt.jsVitePressNest.jsUniAppCapacitorWXTElectronComponentsCLI4. 安装依赖 bashpnpm 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:9301NestJS API：http://localhost:9310项目结构 VUP 采用 Monorepo 架构，创建项目后的结构如下：
初始项目结构 bashvup 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 # 项目说明添加应用后的结构 bashvup 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
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模板下载失败 如果模板下载失败，可以手动更新模板：
bashvup template --updateWindows 路径问题 在 Windows 上如果遇到路径相关问题，确保使用正确的路径分隔符，或使用 Git Bash 或 WSL。
下一步 现在您已经成功创建了第一个 VUP 项目，接下来可以：
📖 了解 VUP 是什么 - 深入了解 VUP 的核心理念和特性🎯 探索模板文档 - 了解不同项目类型的详细使用方法📦 查看功能包文档 - 了解如何使用可复用的功能包🎨 学习主题系统 - 了解如何配置和使用主题🛠️ 配置开发工具 - 提高开发效率和代码质量🚀 设置部署方案 - 了解如何部署您的应用📝 管理版本和日志 - 使用 release-it 管理版本发布获取帮助 📚 查看完整文档💬 提交 Issue🌟 给项目 Star