开发环境配置

开发环境配置指南 (Development Setup Guide)

1. 概述 (Overview)

本页面为 Nomad 项目的开发者提供一个完整、清晰的本地开发环境搭建指南。遵循本指南的步骤，可以确保团队成员拥有一致、可复现的开发环境，从而避免因配置差异导致的问题，顺利开始编码工作。

2. 环境要求 (Prerequisites)

在开始之前，请确保你的系统中已安装以下软件。我们强烈建议使用与规定版本相匹配的工具，以避免不必要的兼容性问题。

• Node.js: v20.15.0 或更高版本
• pnpm: v10.0.0 或更高版本
• Git: 最新稳定版
• PostgreSQL: v15 或更高版本的数据库实例（推荐使用 Docker 在本地快速启动）

3. 首次安装与配置 (First-Time Installation & Setup)

我们提供两种安装方式：自动化一键安装和手动分步安装。对于初次配置，强烈推荐使用自动化脚本。

3.1 自动化一键安装 (Recommended)

此脚本将自动完成大部分繁琐的配置工作。

# 1. 克隆项目仓库
git clone https://github.com/ukeSJTU/nomad.git
cd nomad

# 2. 运行自动化配置脚本
pnpm setup:dev

该脚本会自动执行以下任务：

• 检查 Node.js 和 pnpm 版本。
• 安装所有项目依赖。
• 安装 Playwright E2E 测试所需的浏览器。
• 使用 Husky 配置 Git 钩子。
• 从 .env.example 模板创建 .env 文件。

3.2 手动分步安装 (Alternative)

如果你希望更精细地控制每一步，可以按照以下步骤手动操作：

# 1. 克隆项目仓库
git clone https://github.com/ukeSJTU/nomad.git
cd nomad

# 2. 安装依赖
pnpm install

# 3. 创建环境变量文件
cp .env.example .env

重要提示： 复制后，必须打开 .env 文件并填入必要的环境变量，尤其是 DATABASE_URL，以指向你的本地 PostgreSQL 数据库。例如：postgresql://YourUser:YourPassword@localhost:5432/nomad

# 4. 安装 Husky Git 钩子
pnpm prepare

4. 数据库配置 (Database Setup)

在完成基础安装后，你需要初始化数据库。

# 1. 创建一个名为 'nomad' 的 PostgreSQL 数据库
# (请确保数据库名与你在 .env 文件中设置的一致)
createdb nomad

# 2. 将数据库结构推送到数据库
# (此命令会读取 Drizzle ORM 的 schema 并同步到数据库)
pnpm db:push

# 3. (可选但推荐) 填充开发所需的示例数据
pnpm db:seed

db:seed 命令会为你的数据库创建一些机场、航空公司、航班等初始数据，方便你进行开发和调试。

5. 启动应用 (Running the Application)

现在，你可以启动 Next.js 开发服务器了。

pnpm dev

服务器启动后，你可以在浏览器中访问 http://localhost:3000 查看应用。

6. 验证安装 (Verifying the Setup)

为确保你的环境已完全配置成功，请检查以下几点：

• pnpm dev 命令无错误运行。
• 浏览器成功打开 http://localhost:3000 并显示首页。
• 能够成功注册一个新用户并登录。
• 机票搜索功能可以返回 db:seed 生成的示例航班数据。
• (开发模式下) 访问 http://localhost:3000/docs/api 可以看到自动生成的 API 文档。

7. 常用开发命令 (Common Development Scripts)

在日常开发中，你可能会频繁使用到以下命令。完整的脚本列表请见 package.json。