Next.js FastAPI 模板项目安装与配置指南

1. 项目基础介绍

Next.js FastAPI 模板是一个全栈开发模板，它整合了 Next.js 和 FastAPI 来创建现代化的 Web 应用程序。该项目主要使用 Python 作为后端编程语言，以及 TypeScript 作为前端编程语言。

2. 项目使用的关键技术和框架

• Next.js: 用于构建快速、SEO友好的前端框架。
• FastAPI: 一个高性能的 Python 后端框架。
• SQLAlchemy: 强大的 Python SQL 工具包和 ORM。
• PostgreSQL: 高级开源关系型数据库。
• Pydantic: 使用 Python 类型注解进行数据验证和设置管理。
• Zod: 与 TypeScript 配合，提供端到端的类型安全和模式验证。
• fastapi-users: 提供完整的认证系统，包括 JWT 认证和安全密码散列等。
• Docker 和 Docker Compose: 用于开发和生产环境的一致性容器化。
• 其他: 包括 Pytest、ESLint、Chokidar 等工具和库。

3. 项目安装和配置的准备工作

在开始安装之前，请确保您的开发环境中已经安装了以下工具：

• Python 3.12: 项目后端所需的 Python 版本。
• Node.js 和 npm: 用于运行前端项目。
• pnpm: 用于管理前端项目的包。
• Docker: 用于容器化应用。
• Docker Compose: 用于定义和运行多容器 Docker 应用程序。

详细安装步骤

步骤 1: 克隆项目

首先，从 GitHub 上克隆项目到本地：

git clone https://github.com/vintasoftware/nextjs-fastapi-template.git
cd nextjs-fastapi-template

步骤 2: 设置环境变量

• 对于后端 (fastapi_backend):

cd fastapi_backend
cp .env.example .env

编辑 .env 文件，更新所需的变量，如数据库配置、邮件服务等。

• 对于前端 (nextjs-frontend):

cd nextjs-frontend
cp .env.example .env

前端的环境变量通常不需要修改。

步骤 3: 安装依赖

• 对于后端，安装 Python 依赖：

uv sync

• 对于前端，安装 Node.js 依赖：

pnpm install

步骤 4: 运行数据库

使用 Docker 运行数据库容器：

docker compose build db
docker compose up -d db

应用数据库迁移：

make docker-migrate-db

步骤 5: 构建项目

• 使用 Docker 构建：

make docker-build

• 不使用 Docker 构建：

  • 后端：

  make start-backend
  

  • 前端：

  pnpm run dev
  

按照以上步骤，您应该能够成功安装并运行 Next.js FastAPI 模板项目。