如何在 Vercel Postgres 中安全地构建动态 SQL 查询

本文介绍使用 @vercel/postgres 时，如何通过参数化 .query() 方法动态拼接 WHERE 条件，避免 sql 注入，同时保持类型安全与可维护性。

本文介绍使用 @vercel/postgres 时，如何通过参数化 `.query()` 方法动态拼接 where 条件，避免 sql 注入，同时保持类型安全与可维护性。

在使用 @vercel/postgres 开发 Node.js 应用时，常需根据运行时参数（如 categoryId、typeId）构造条件可变的 SQL 查询。虽然其推荐的模板字面量语法（如 sqlSELECT * FROM products WHERE id=$1）简洁安全，但它**不支持运行时拼接字符串后再次注入模板标签**——即 `sql`${dynamicQuery} 会直接报错。因此，必须采用替代方案，在保障安全性前提下实现动态查询。

✅ 正确做法：使用 .query() + 参数数组

@vercel/postgres 的 sql.query() 方法接受两个参数：SQL 字符串（含 $1, $2 占位符）和参数值数组。这是构建动态查询的安全且官方支持的方式：

import { sql } from '@vercel/postgres';  async function getProducts(categoryId, typeId = NULL) {   let query = 'SELECT * FROM products WHERE categoryId = $1';   let params = [categoryId];    if (typeId != null) {     query += ' AND typeId = $2';     params.push(typeId);   }    const result = await sql.query(query, params);   return result.rows; }

✅ 优势说明：

• 所有用户输入均通过参数数组传入，由底层驱动自动转义，彻底杜绝 SQL 注入；
• 占位符 $1, $2 严格按顺序绑定，类型推断清晰（postgresql 支持类型推导）；
• 逻辑直观，易于扩展更多条件（如 status, minPrice 等）。

⚠️ 关键注意事项

• 严禁字符串拼接用户输入：以下写法极度危险，绝对禁止：

  // ❌ 危险！可能引发 SQL 注入 const query = `SELECT * FROM products WHERE categoryId = ${categoryId}`;

• null 与 undefined 区分处理：建议统一用 null 表示“未提供”，避免 undefined 导致意外行为（如 WHERE typeId = undefined 生成无效 SQL）；
• 字段名/表名不可参数化：$1 仅适用于值（values），不能用于动态列名或表名。若需动态表名，应通过白名单校验后硬编码，或改用 ORM；
• 性能提示：简单条件分支（如本例）对性能无影响；但高频复杂动态查询建议预编译（PREPARE）或引入查询构建器。

? 进阶建议：何时考虑替代方案？

当动态查询逻辑日益复杂（例如支持多字段模糊搜索、范围过滤、排序、分页组合），手动拼接易出错且难以维护。此时推荐：

• 使用轻量级查询构建器：如 kysely（typescript 优先，类型安全强）或 pg-builder；
• 或选用成熟 ORM：如 Drizzle ORM（Vercel 官方推荐）或 Prisma，它们内置安全的动态 where 构建能力：

  // Drizzle 示例（类型安全） const conditions = eq(products.categoryId, categoryId); if (typeId) conditions = and(conditions, eq(products.typeId, typeId)); const result = await db.select().from(products).where(conditions);

总之，.query() 是 @vercel/postgres 动态查询的基石方法——它在灵活性与安全性之间取得最佳平衡。牢记“值用 $n，结构靠逻辑”，即可稳健支撑从简单筛选到中等复杂度的业务查询需求。