Vue3与Nest.js前后端分离项目实战指南

本文将详细介绍如何从零开始，运用 Vue 3 作为前端框架，Nest.js 作为后端框架，构建一个现代的全栈应用。同时，会总结在开发、联调、部署等环节中的关键实践与常见问题解决方案。

一、项目结构规划

在编码之前，合理的项目结构是高效开发的基础。推荐采用前后端完全分离的目录结构：

project-root/
├── frontend/          # Vue3 前端项目
│   ├── src/
│   ├── vite.config.js
│   └── package.json
├── backend/           # Nest.js 后端项目
│   ├── src/
│   ├── main.ts
│   └── package.json
└── README.md

这种结构使前后端项目独立，便于各自的开发、调试，在部署时也可以灵活选择分开部署或整合。

二、创建与配置 Vue3 前端项目

1. 创建项目

使用 Vite 可以快速搭建一个高性能的 Vue3 项目，其启动速度和热更新体验极佳。

npm create vite@latest frontend --template vue
cd frontend
npm install

2. 使用 Composition API

在 Vue3 中，组合式 API (Composition API) 提供了更灵活的逻辑组织方式。

<script setup>
import { ref } from 'vue'
const message = ref('Hello Vue3 + Nest!')
</script>

<template>
  <h1>{{ message }}</h1>
</template>

3. 配置开发环境代理（解决跨域）

在本地开发时，前端运行在 localhost:5173，后端运行在 localhost:5000，存在跨域问题。通过在 vite.config.js 中配置代理可以轻松解决。

// frontend/vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000', // 后端服务地址
        changeOrigin: true,
      },
    },
  },
})

配置后，前端发往 /api/... 的请求会被自动代理到 http://localhost:5000/api/...。

三、创建与配置 Nest.js 后端项目

1. 创建项目

Nest.js 是一个用于构建高效、可扩展服务端应用的渐进式 Node.js 框架。首先全局安装 CLI 并创建项目。

npm i -g @nestjs/cli
nest new backend
cd backend
npm run start:dev

2. 创建控制器与服务

Nest.js 的核心特色之一是使用装饰器来清晰地定义模块、控制器和服务。下面创建一个简单的接口。

// backend/src/app.controller.ts
import { Controller, Get } from '@nestjs/common';

@Controller('api') // 定义路由前缀为 /api
export class AppController {
  @Get('hello') // 定义 GET /api/hello 接口
  getHello() {
    return { message: 'Hello from Nest.js!' };
  }
}

3. 运行与测试接口

启动后端服务后，访问 http://localhost:5000/api/hello，将会看到返回的 JSON 数据。

{ "message": "Hello from Nest.js!" }

四、前后端联调实践

前端需要通过 HTTP 请求调用后端接口。我们可以使用 axios 库。

首先，在前端项目中安装 axios：

npm install axios

然后，创建一个 API 请求模块：

// frontend/src/api/index.js
import axios from 'axios';

// 创建一个配置了基础URL的axios实例
const request = axios.create({
  baseURL: '/api', // 与vite代理和Nest控制器前缀匹配
});

export const getHello = () => {
  return request.get('/hello');
};

在 Vue 组件中使用这个接口：

<script setup>
import { onMounted, ref } from 'vue'
import { getHello } from './api/index.js'

const backendMessage = ref('')

onMounted(async () => {
  const res = await getHello()
  backendMessage.value = res.data.message
})
</script>

<template>
  <div>
    <h1>前端页面</h1>
    <p>后端说：{{ backendMessage }}</p>
  </div>
</template>

五、生产环境跨域（CORS）配置

Vite 的代理配置仅在开发模式下生效。当项目部署到生产环境时，必须在 Nest.js 后端显式启用 CORS。

在 main.ts 文件中进行配置：

// backend/src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 启用CORS，并配置允许的源
  app.enableCors({
    origin: 'https://你的前端域名.com', // 生产环境前端地址
    // 或在开发时允许本地地址
    // origin: ['http://localhost:5173'],
    credentials: true, // 如果需要携带cookie等凭证
  });

  await app.listen(process.env.PORT || 5000);
}
bootstrap();

六、接口规范与模块化开发

Nest.js 强烈推荐模块化设计。例如，对于“用户”功能，可以使用 CLI 快速生成完整模块。

nest g module user
nest g controller user
nest g service user

命令执行后，会自动生成结构清晰的代码文件：

src/
├── user/
│   ├── user.module.ts
│   ├── user.controller.ts
│   └── user.service.ts

在控制器中，可以这样组织接口：

// backend/src/user/user.controller.ts
import { Controller, Get } from '@nestjs/common';
import { UserService } from './user.service';

@Controller('api/user') // 控制器路径为 /api/user
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get() // GET /api/user
  findAll() {
    return this.userService.findAll();
  }
}

七、环境变量管理

后端环境变量

在 Nest.js 项目根目录创建 .env 文件：

PORT=5000
DATABASE_URL=mysql://root:password@localhost:3306/mydb

修改 main.ts 以使用环境变量中的端口：

await app.listen(process.env.PORT || 5000);

前端环境变量

Vite 使用 VITE_ 开头的环境变量。在项目根目录创建 .env.development 和 .env.production。

# .env.development
VITE_API_BASE_URL=/api

# .env.production
VITE_API_BASE_URL=https://api.yourdomain.com

在前端代码中通过 import.meta.env 访问：

const baseURL = import.meta.env.VITE_API_BASE_URL;

八、部署注意事项

不同环境的部署策略有所不同：

场景	前端部署方案	后端部署要点
本地开发	npm run dev，端口 5173	npm run start:dev，端口 5000
生产环境	npm run build，生成 dist 静态文件	构建后运行，需配置 CORS、环境变量
静态托管	可使用 Nginx、对象存储、Netlify 等托管 dist 文件夹	独立部署在服务器或云服务上
整合部署	可将 dist 文件夹放入 Nest.js，使用 app.useStaticAssets 托管	需配置静态资源中间件，并处理好 API 路由与静态文件路由的优先级

九、常见问题与解决方案

1. 跨域问题 (CORS)

   • 开发环境：使用 Vite 代理配置。
   • 生产环境：务必在 Nest.js 中使用 app.enableCors() 或在 Nginx 反向代理中配置。

2. 接口路径 404

   • 检查前端请求的路径（如 /api/user）是否与 Nest.js 控制器的 @Controller('api') 前缀及方法装饰器 @Get('user') 拼接的路径完全匹配。

3. TypeORM 数据库连接错误

   • 确认已安装所需依赖：npm i @nestjs/typeorm typeorm mysql2（以 MySQL 为例）。
   • 在模块导入时，检查实体（Entity）文件路径是否正确。

4. 生产环境端口冲突

   • 修改后端 .env 文件中的 PORT 变量，避免与服务器上其他服务端口冲突。

遵循以上步骤和注意事项，你将能够顺利地使用 Vue3 和 Nest.js 搭建起一个结构清晰、易于维护的前后端分离应用。