Soybean Admin 快速上手指南：从安装到部署全流程

Soybean Admin 快速上手指南：从安装到部署全流程

【免费下载链接】soybean-admin A fresh and elegant admin template, based on Vue3,Vite3,TypeScript,NaiveUI and UnoCSS [一个基于Vue3、Vite3、TypeScript、NaiveUI 和 UnoCSS的清新优雅的中后台模版] 项目地址: https://gitcode.com/gh_mirrors/so/soybean-admin

技术环境要求（点击展开）

• Node.js：v20.19.0 或更高版本 ⓘ 推荐使用 nvm 管理多版本 Node
• 包管理器：pnpm 10.5.0+ / npm 9.0+ / yarn 1.22+
• Git：用于克隆仓库和版本控制
• 操作系统：Windows 10+、macOS 12+ 或 Linux（Ubuntu 20.04+）

[!TIP] 不确定环境是否达标？执行 node -v && pnpm -v 快速检查版本

3分钟快速启动

按照以下步骤，3分钟内启动项目：

1. 获取代码

   git clone https://gitcode.com/gh_mirrors/so/soybean-admin
   cd soybean-admin
   

2. 安装依赖

   # 使用pnpm（推荐）
   pnpm install
   
   # 或使用npm
   npm install
   
   # 或使用yarn
   yarn install
   

3. 启动开发服务器

   # 开发环境（默认）
   pnpm dev
   
   # 生产环境预览
   pnpm dev:prod
   

4. 访问应用
   打开浏览器访问 http://localhost:5173 ⓘ 默认端口可在 vite.config.ts 中修改

项目结构解密

核心目录导航

soybean-admin/
├── packages/        # 模块化功能包
├── public/          # 静态资源根目录
├── src/             # 应用源代码
│   ├── assets/      # 图片/图标等资源
│   ├── components/  # 可复用组件库
│   ├── views/       # 页面视图组件
│   ├── router/      # 路由配置中心
│   └── store/       # 状态管理模块
└── 配置文件区

[!WARNING] 常见误区 ❌ 不要直接修改 packages/ 下的代码，这些是独立模块 ✅ 业务代码应放在 src/views 或 src/components 目录

项目结构思维导图

环境定制指南

启动命令全解析

命令	作用	适用场景
pnpm dev	启动测试环境开发服务器	日常开发调试
pnpm dev:prod	启动生产环境开发服务器	模拟生产环境验证
pnpm build	构建生产环境代码	部署前打包
pnpm preview	预览构建产物	打包后本地验证
pnpm typecheck	TypeScript类型检查	提交代码前校验

[!TIP] 自定义启动端口：pnpm dev --port 8080

配置文件指南

核心配置文件

文件名	作用	关键配置项
vite.config.ts	构建工具配置	server.port、plugins
tsconfig.json	TypeScript配置	compilerOptions.target
uno.config.ts	CSS引擎配置	theme.colors、rules

环境变量设置

1. 在项目根目录创建环境文件：

   .env                # 通用环境变量
   .env.development    # 开发环境变量
   .env.production     # 生产环境变量
   

2. 环境变量格式：

   VITE_APP_TITLE=我的管理系统
   VITE_API_BASE_URL=/api
   

[!WARNING] 常见误区 环境变量必须以 VITE_ 开头才能被客户端访问，如 VITE_API_URL

排错速查手册

启动失败类

端口被占用

Error: Port 5173 is already in use

解决方法：

# 方法1：指定其他端口
pnpm dev --port 5174

# 方法2：关闭占用进程
# Windows
netstat -ano | findstr :5173
taskkill /PID <进程ID> /F

# macOS/Linux
lsof -i :5173
kill -9 <进程ID>

依赖安装失败

Error: Cannot find module 'xxxxx'

解决方法：

# 清除缓存后重装
pnpm cache clean
pnpm install

# 或删除node_modules后重装
rm -rf node_modules pnpm-lock.yaml
pnpm install

运行时错误

路由跳转失败

症状：页面空白或控制台提示路由错误
检查：

1. src/router/routes 中是否正确定义路由
2. 组件是否通过 definePage 正确导出
3. 路由权限配置是否正确

构建错误

类型检查失败

error TS2322: Type 'string' is not assignable to type 'number'

解决方法：

1. 修复类型错误后再构建
2. 临时跳过类型检查（不推荐）：

   pnpm build --no-type-check
   

Q&A常见问题

Q: 如何修改默认主题颜色？
A: 编辑 src/theme/vars.ts 文件中的 primaryColor 变量，支持十六进制或RGB值。

Q: 如何添加新页面？
A: 1. 在 src/views 下创建页面组件
2. 在 src/router/routes 中添加路由配置
3. 执行 pnpm gen-route 更新路由

Q: 开发时API请求跨域怎么办？
A: 在 vite.config.ts 中配置server.proxy：

server: {
  proxy: {
    '/api': {
      target: 'http://backend-server.com',
      changeOrigin: true
    }
  }
}

构建与部署

生产环境构建

# 构建生产版本
pnpm build

# 构建测试环境版本
pnpm build:test

构建产物会生成在 dist/ 目录，可直接部署到Nginx、Apache等Web服务器。

多环境部署指南

部署到Nginx（点击查看）

1. 安装Nginx并创建配置文件：

   server {
     listen 80;
     server_name admin.example.com;
   
     location / {
       root /path/to/soybean-admin/dist;
       index index.html;
       try_files $uri $uri/ /index.html;
     }
   }
   

2. 重启Nginx服务：

   systemctl restart nginx
   

部署到Netlify（点击查看）

1. 设置构建命令：pnpm build
2. 输出目录：dist
3. 添加环境变量：NODE_VERSION=20.19.0

[!TIP] 部署小贴士 生产环境建议设置：

• 启用GZIP压缩
• 配置缓存策略
• 使用HTTPS协议

【免费下载链接】soybean-admin A fresh and elegant admin template, based on Vue3,Vite3,TypeScript,NaiveUI and UnoCSS [一个基于Vue3、Vite3、TypeScript、NaiveUI 和 UnoCSS的清新优雅的中后台模版] 项目地址: https://gitcode.com/gh_mirrors/so/soybean-admin