knex默认不输出sql日志，必须显式配置debug: true才能打印完整sql、参数及耗时；可使用.tosql()或.tostring()预览sql而不执行；vscode终端乱码需确认utf-8编码及连接字符集；日志存文件可通过log配置项或重定向console实现。
Knex 的 SQL 日志为什么没输出？
默认情况下，Knex 不会打印任何 SQL，哪怕你写了 knex('users').select()，控制台也静默无声。这不是 VSCode 的问题，也不是 Node 环境没配好，而是 Knex 本身关闭了查询日志——它只在明确启用调试模式时才吐 SQL。
关键开关是 debug: true 配置项，必须写进 knexfile.ts 或初始化实例的 config 对象里：
export const config: Knex.Config = {
client: 'mysql2',
connection: { /* ... */ },
debug: true // ← 必须显式设为 true
};
-
debug: true会把完整 SQL、绑定参数、执行耗时全打到console.log，不依赖 VSCode 插件或额外工具 - 如果用的是环境变量控制（如
process.env.DEBUG === 'true'），记得在启动命令里传进去：DEBUG=true node index.js - 注意：某些旧版
@types/knex会把debug标为可选但实际未生效，v2+ 官方类型已正确定义，建议删掉@types/knex避免冲突
如何只打印 SQL 而不触发真实查询？
调试阶段常想看生成的 SQL 是什么，又不想真连数据库跑——比如字段名拼错、where 条件漏写，直接执行可能改错数据。Knex 提供了安全的预览方式：.toSQL() 和 .toString()。
它们返回字符串，不发请求，适合快速验证逻辑：
const query = knex('users').where('id', 1).select('name', 'email');
console.log(query.toSQL()); // { method: 'select', sql: 'select "name", "email" from "users" where "id" = ?', bindings: [1] }
console.log(query.toString()); // 'select "name", "email" from "users" where "id" = 1'
-
.toSQL()返回对象，含sql和bindings，更贴近真实执行上下文 -
.toString()直接拼接参数（仅限简单值），遇null、undefined或复杂表达式会出错，慎用于生产调试 - 别在
.then()里调.toSQL()——它必须在 query 构建链上提前调用，异步链之后就失效了
VSCode 终端里 SQL 日志被截断或乱码怎么办？
常见现象：SQL 打印出来是 select "name", "email" from "users" where "id" = ?，后面跟着一堆 [object Object] 或中文变 ???。这通常不是 Knex 问题，而是终端渲染或编码链路断在某环。
- 确认 VSCode 终端编码为 UTF-8：右下角点击编码 → 选
UTF-8（不是“自动检测”） - MySQL 连接字符串加
charset=utf8mb4，PostgreSQL 加client_encoding=utf8，否则驱动解码和终端显示不一致 - 避免在
console.log里直接打印整个query.toSQL()对象——JS 默认 toString() 会丢内容，改用console.dir(query.toSQL(), { depth: null }) - 如果用了
nodemon或ts-node，确保它们没劫持console输出（例如某些日志聚合插件会过滤非字符串）
想把 SQL 日志存文件而不是刷屏？
开发中频繁刷屏干扰大，尤其配合 watch 模式时。Knex 不提供内置文件输出，但可以用 Node 原生 fs.createWriteStream 接管日志流。
最简做法：重定向 console.log 的输出目标（仅限调试阶段，勿用于生产）：
import fs from 'fs';
const logStream = fs.createWriteStream('knex-debug.log', { flags: 'a' });
console.log = (...args) => {
logStream.write(`${new Date().toISOString()} ${args.join(' ')}\n`);
};
- 这个 patch 要放在
knex实例创建之前，否则日志已在原 console 流里刷走了 - 更稳妥的方式是用 Knex 的
log配置项，自定义 handler： -
log: { warn: msg => fs.appendFile('knex-warn.log', msg + '\n', () => {}) }，但注意 Node 异步写入可能丢日志，高并发下需加队列或用pino等专业日志库
真正难的不是打印 SQL，而是分辨哪些 SQL 是你写的、哪些是 Knex 自动补的（比如事务 BEGIN/COMMIT）、哪些来自迁移或种子——得靠 debug 输出里的 method 字段和调用栈源头定位，别光盯着 sql 字符串。
