Next.js 项目中使用 PostgreSQL 数据库的配置与数据初始化指南

2025-06-14 06:50:03作者：郜逊炳

在 Next.js 项目中配置和使用 PostgreSQL 数据库是一个常见的需求，但在实际操作中开发者可能会遇到各种问题。本文将详细介绍如何在 Next.js 项目中正确配置 PostgreSQL 数据库，并解决数据初始化过程中可能遇到的典型问题。

数据库连接配置

首先需要正确配置数据库连接参数。对于本地开发环境，特别是使用 Docker 容器运行 PostgreSQL 的情况，需要注意以下几点：

确保 Docker 容器端口映射正确，例如 -p 5433:5432 表示将容器内的 5432 端口映射到主机的 5433 端口
在环境变量中配置正确的连接参数：
- POSTGRES_USER：数据库用户名
- POSTGRES_PASSWORD：数据库密码
- POSTGRES_HOST：数据库主机地址
- POSTGRES_PORT：数据库端口（使用映射后的主机端口）
- POSTGRES_DATABASE：数据库名称

数据库客户端选择

Next.js 官方文档可能推荐使用特定数据库客户端，但在实际开发中，根据环境不同需要灵活选择：

对于 Vercel 部署环境，可以使用 @vercel/postgres
对于本地开发环境，特别是使用原生 PostgreSQL 时，应该安装 pg 客户端库

安装命令：

pnpm add pg

数据初始化脚本编写

数据初始化脚本需要正确处理以下方面：

创建必要的扩展（如 uuid-ossp）
建表前检查表是否已存在
使用参数化查询防止 SQL 注入
处理密码哈希（使用 bcrypt）
使用事务确保数据一致性

典型的数据初始化函数结构如下：

async function seedUsers() {
    // 创建扩展
    await client.query(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
    
    // 创建表
    await client.query(`
        CREATE TABLE IF NOT EXISTS users (
            id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
            name VARCHAR(255) NOT NULL,
            email TEXT NOT NULL UNIQUE,
            password TEXT NOT NULL
        );
    `);

    // 插入数据
    const insertedUsers = await Promise.all(
        users.map(async (user) => {
            const hashedPassword = await bcrypt.hash(user.password, 10);
            return client.query(
                `INSERT INTO users (id, name, email, password)
                 VALUES ($1, $2, $3, $4)
                 ON CONFLICT (id) DO NOTHING;`,
                [user.id, user.name, user.email, hashedPassword]
            );
        })
    );

    return insertedUsers;
}