Fastify 日志、错误处理与生产实践

应用从「能跑」到「能上线」，需补齐日志、错误处理、配置、优雅关闭、安全与性能等环节。Fastify 默认集成 pino 结构化日志，配合统一错误处理和实例配置，可以低成本达到生产级水平。

前置知识：先阅读钩子 Hooks 与生命周期与插件与封装机制。

一、内置日志：Pino

Fastify 默认不打印日志（logger: false），开启后即获得极快的结构化 JSON 日志（Pino 号称比默认 logger 快约 5 倍）。

1.1 开启日志

import Fastify from 'fastify';

const app = Fastify({ logger: true });

1.2 请求级日志

每个 req 自带 req.log，自动携带 reqId、请求方法、URL 等上下文，便于串联链路：

app.get('/order/:id', async (req) => {
  req.log.info({ orderId: req.params.id }, 'fetching order');
  const order = await getOrder(req.params.id);
  req.log.debug({ order }, 'fetched');
  return order;
});

1.3 配置日志

const app = Fastify({
  logger: {
    level: process.env.LOG_LEVEL || 'info',
    redact: ['req.headers.authorization', 'body.password'], // 脱敏字段
    transport: process.env.NODE_ENV === 'development'
      ? { target: 'pino-pretty' }               // 开发可读输出
      : undefined,                              // 生产输出 JSON
  },
});

1.4 日志常见字段

字段	描述
`reqId`	由 Fastify 生成的请求追踪 ID（可自定义）
`ts`	时间戳（epoch ms）
`level`	日志级别
`msg`	日志消息

二、错误处理

2.1 内置错误标准化

Schema 校验失败、路由未命中等都返回统一结构的错误体：

json

{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "..." }

2.2 自定义错误 + `setErrorHandler`

用 setErrorHandler 统一拦截所有未处理的错误：

class AppError extends Error {
  constructor(code, message, statusCode = 400) {
    super(message);
    this.code = code;
    this.statusCode = statusCode;
  }
}

app.setErrorHandler((error, req, reply) => {
  const statusCode = error.statusCode || 500;
  req.log.error({ error }, 'unhandled error');

  // 业务可见错误
  if (error instanceof AppError) {
    return reply.code(statusCode).send({ ok: false, code: error.code, message: error.message });
  }

  // 内部错误：生产环境不泄露细节
  return reply.code(statusCode).send({
    ok: false,
    code: 'INTERNAL_ERROR',
    message: process.env.NODE_ENV === 'development' ? error.message : '服务器内部错误',
  });
});

业务侧抛出：

app.get('/users/:id', async (req) => {
  const user = await findUser(req.params.id);
  if (!user) throw new AppError('USER_NOT_FOUND', '用户不存在', 404);
  return user;
});

2.3 未捕获异步异常

async Handler 抛出的异常会被 Fastify 捕获并进入错误流程；对非 async（遗留回调式）Handler 需手动 reply.send(err) 或包一层。

三、常见生产配置

3.1 实例级配置项

const app = Fastify({
  logger: true,
  trustProxy: true,          // 代理后获取真实 IP 与 protocol
  bodyLimit: 1024 * 1024,    // 请求体上限 1MB
  maxParamLength: 100,       // 路径参数长度上限
  requestTimeout: 30_000,    // 请求超时
  keepAliveTimeout: 5_000,
});

3.2 通过 `CONFIG`/`CLI` 暴露配置

结合 --env-file（Node 20+）或在入口读取环境变量：

bash

node --env-file=.env app.js

const app = Fastify({
  logger: { level: process.env.LOG_LEVEL },
  trustProxy: process.env.TRUST_PROXY === 'true',
});

四、优雅关闭

避免进程被强杀时丢失进行中的请求或连接。

4.1 监听进程信号

const app = Fastify({ logger: true });

async function shutdown(signal) {
  app.log.info({ signal }, 'shutting down');
  await app.close(); // 触发 onClose 钩子，等待进行中请求完成
  process.exit(0);
}

process.on('SIGINT', () => shutdown('SIGINT'));
process.on('SIGTERM', () => shutdown('SIGTERM'));

4.2 在 `onClose` 释放资源

app.addHook('onClose', async () => {
  await db.disconnect();
  await cache.close();
});

五、性能与安全加固

5.1 基础性能手段

手段	说明
开启 Schema	使用预编译序列化替代手写 `JSON.stringify`
Node 原生压力	压测用 `autocannon`：`npx autocannon -c 100 -d 10 http://localhost:3000/`
压缩	`@fastify/compress` 开启 Gzip/Brotli
缓存	对幂等接口做响应级/请求级缓存

5.2 安全清单

app.register(cors, { origin: allowList });
app.register(helmet);
app.register(rateLimit, { max: 100, timeWindow: '1 minute' });
// 校验 + 请求体上限 + 脱敏（logger.redact）已在前面覆盖

六、部署

6.1 多进程：Node cluster 或 PM2

Fastify 单实例受限于单核。生产上常用 PROCESS 级集群：

// 简洁多进程方案（Node 的 cluster 封装）
import { availableParallelism } from 'node:os';
import cluster from 'node:cluster';

if (cluster.isPrimary) {
  for (let i = 0; i < availableParallelism(); i++) cluster.fork();
} else {
  const { start } = await import('./startup.js');
  start();
}

PM2 也能以 cluster 模式管理：

bash

pm2 start app.js -i 4   # 启动 4 个 worker

6.2 Docker

dockerfile

FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev

FROM node:22-slim
WORKDIR /app
COPY --from=build /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "app.js"]

bash

docker build -t fastify-api .
docker run -p 3000:3000 fastify-api

6.3 反向代理（Nginx）

11-Nginx

upstream fastify {
    server 127.0.0.1:3000;
}
server {
    listen 80;
    location / {
        proxy_pass http://fastify;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

配合 trustProxy: true 才能在 req.ip 拿到真实客户端 IP。

常见问题

Q1: 为什么生产日志是 JSON 多行拼接？

Pino 输出 JSON 供日志平台统一采集。开发期可加 pino-pretty 让终端可读，两者互不干扰。

Q2: 请求体过大报 `FST_ERR_CTP_BODY_TOO_LARGE`？

调大 bodyLimit：Fastify({ bodyLimit: 2 * 1024 * 1024 })；或在路由级 config 覆盖。

Q3: 如何统一前端/网关的错误码？

在 setErrorHandler 里把所有错误映射为 { ok, code, message }，保证客户端解析一致。

下一步学习

Fastify 实战项目：综合路由、Schema、插件、钩子与错误处理构建一个完整 API。

Fastify 日志、错误处理与生产实践

前置知识：先阅读钩子 Hooks 与生命周期与插件与封装机制。

一、内置日志：Pino

Fastify 默认不打印日志（logger: false），开启后即获得极快的结构化 JSON 日志（Pino 号称比默认 logger 快约 5 倍）。

1.1 开启日志

import Fastify from 'fastify';

const app = Fastify({ logger: true });

1.2 请求级日志

每个 req 自带 req.log，自动携带 reqId、请求方法、URL 等上下文，便于串联链路：

app.get('/order/:id', async (req) => {
  req.log.info({ orderId: req.params.id }, 'fetching order');
  const order = await getOrder(req.params.id);
  req.log.debug({ order }, 'fetched');
  return order;
});

1.3 配置日志

const app = Fastify({
  logger: {
    level: process.env.LOG_LEVEL || 'info',
    redact: ['req.headers.authorization', 'body.password'], // 脱敏字段
    transport: process.env.NODE_ENV === 'development'
      ? { target: 'pino-pretty' }               // 开发可读输出
      : undefined,                              // 生产输出 JSON
  },
});

1.4 日志常见字段

字段	描述
`reqId`	由 Fastify 生成的请求追踪 ID（可自定义）
`ts`	时间戳（epoch ms）
`level`	日志级别
`msg`	日志消息

二、错误处理

2.1 内置错误标准化

Schema 校验失败、路由未命中等都返回统一结构的错误体：

json

{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "..." }

2.2 自定义错误 + `setErrorHandler`

用 setErrorHandler 统一拦截所有未处理的错误：

class AppError extends Error {
  constructor(code, message, statusCode = 400) {
    super(message);
    this.code = code;
    this.statusCode = statusCode;
  }
}

app.setErrorHandler((error, req, reply) => {
  const statusCode = error.statusCode || 500;
  req.log.error({ error }, 'unhandled error');

  // 业务可见错误
  if (error instanceof AppError) {
    return reply.code(statusCode).send({ ok: false, code: error.code, message: error.message });
  }

  // 内部错误：生产环境不泄露细节
  return reply.code(statusCode).send({
    ok: false,
    code: 'INTERNAL_ERROR',
    message: process.env.NODE_ENV === 'development' ? error.message : '服务器内部错误',
  });
});

业务侧抛出：

app.get('/users/:id', async (req) => {
  const user = await findUser(req.params.id);
  if (!user) throw new AppError('USER_NOT_FOUND', '用户不存在', 404);
  return user;
});

2.3 未捕获异步异常

async Handler 抛出的异常会被 Fastify 捕获并进入错误流程；对非 async（遗留回调式）Handler 需手动 reply.send(err) 或包一层。

三、常见生产配置

3.1 实例级配置项

const app = Fastify({
  logger: true,
  trustProxy: true,          // 代理后获取真实 IP 与 protocol
  bodyLimit: 1024 * 1024,    // 请求体上限 1MB
  maxParamLength: 100,       // 路径参数长度上限
  requestTimeout: 30_000,    // 请求超时
  keepAliveTimeout: 5_000,
});

3.2 通过 `CONFIG`/`CLI` 暴露配置

结合 --env-file（Node 20+）或在入口读取环境变量：

bash

node --env-file=.env app.js

const app = Fastify({
  logger: { level: process.env.LOG_LEVEL },
  trustProxy: process.env.TRUST_PROXY === 'true',
});

四、优雅关闭

避免进程被强杀时丢失进行中的请求或连接。

4.1 监听进程信号

const app = Fastify({ logger: true });

async function shutdown(signal) {
  app.log.info({ signal }, 'shutting down');
  await app.close(); // 触发 onClose 钩子，等待进行中请求完成
  process.exit(0);
}

process.on('SIGINT', () => shutdown('SIGINT'));
process.on('SIGTERM', () => shutdown('SIGTERM'));

4.2 在 `onClose` 释放资源

app.addHook('onClose', async () => {
  await db.disconnect();
  await cache.close();
});

五、性能与安全加固

5.1 基础性能手段

手段	说明
开启 Schema	使用预编译序列化替代手写 `JSON.stringify`
Node 原生压力	压测用 `autocannon`：`npx autocannon -c 100 -d 10 http://localhost:3000/`
压缩	`@fastify/compress` 开启 Gzip/Brotli
缓存	对幂等接口做响应级/请求级缓存

5.2 安全清单

app.register(cors, { origin: allowList });
app.register(helmet);
app.register(rateLimit, { max: 100, timeWindow: '1 minute' });
// 校验 + 请求体上限 + 脱敏（logger.redact）已在前面覆盖

六、部署

6.1 多进程：Node cluster 或 PM2

Fastify 单实例受限于单核。生产上常用 PROCESS 级集群：

// 简洁多进程方案（Node 的 cluster 封装）
import { availableParallelism } from 'node:os';
import cluster from 'node:cluster';

if (cluster.isPrimary) {
  for (let i = 0; i < availableParallelism(); i++) cluster.fork();
} else {
  const { start } = await import('./startup.js');
  start();
}

PM2 也能以 cluster 模式管理：

bash

pm2 start app.js -i 4   # 启动 4 个 worker

6.2 Docker

dockerfile

FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev

FROM node:22-slim
WORKDIR /app
COPY --from=build /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "app.js"]

bash

docker build -t fastify-api .
docker run -p 3000:3000 fastify-api

6.3 反向代理（Nginx）

11-Nginx

upstream fastify {
    server 127.0.0.1:3000;
}
server {
    listen 80;
    location / {
        proxy_pass http://fastify;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

配合 trustProxy: true 才能在 req.ip 拿到真实客户端 IP。

常见问题

Q1: 为什么生产日志是 JSON 多行拼接？

Pino 输出 JSON 供日志平台统一采集。开发期可加 pino-pretty 让终端可读，两者互不干扰。

Q2: 请求体过大报 `FST_ERR_CTP_BODY_TOO_LARGE`？

调大 bodyLimit：Fastify({ bodyLimit: 2 * 1024 * 1024 })；或在路由级 config 覆盖。

Q3: 如何统一前端/网关的错误码？

在 setErrorHandler 里把所有错误映射为 { ok, code, message }，保证客户端解析一致。

下一步学习

Fastify 实战项目：综合路由、Schema、插件、钩子与错误处理构建一个完整 API。

Fastify 日志、错误处理与生产实践

一、内置日志：Pino

1.1 开启日志

1.2 请求级日志

1.3 配置日志

1.4 日志常见字段

二、错误处理

2.1 内置错误标准化

2.2 自定义错误 + setErrorHandler

2.3 未捕获异步异常

三、常见生产配置

3.1 实例级配置项

3.2 通过 CONFIG/CLI 暴露配置

四、优雅关闭

4.1 监听进程信号

4.2 在 onClose 释放资源

五、性能与安全加固

5.1 基础性能手段

5.2 安全清单

六、部署

6.1 多进程：Node cluster 或 PM2

6.2 Docker

6.3 反向代理（Nginx）

常见问题

Q1: 为什么生产日志是 JSON 多行拼接？

Q2: 请求体过大报 FST_ERR_CTP_BODY_TOO_LARGE？

Q3: 如何统一前端/网关的错误码？

下一步学习

相关文档

Fastify 日志、错误处理与生产实践

一、内置日志：Pino

1.1 开启日志

1.2 请求级日志

1.3 配置日志

1.4 日志常见字段

二、错误处理

2.1 内置错误标准化

2.2 自定义错误 + setErrorHandler

2.3 未捕获异步异常

三、常见生产配置

3.1 实例级配置项

3.2 通过 CONFIG/CLI 暴露配置

四、优雅关闭

4.1 监听进程信号

4.2 在 onClose 释放资源

五、性能与安全加固

5.1 基础性能手段

5.2 安全清单

六、部署

6.1 多进程：Node cluster 或 PM2

6.2 Docker

6.3 反向代理（Nginx）

常见问题

Q1: 为什么生产日志是 JSON 多行拼接？

Q2: 请求体过大报 FST_ERR_CTP_BODY_TOO_LARGE？

Q3: 如何统一前端/网关的错误码？

下一步学习

相关文档

2.2 自定义错误 + `setErrorHandler`

3.2 通过 `CONFIG`/`CLI` 暴露配置

4.2 在 `onClose` 释放资源

Q2: 请求体过大报 `FST_ERR_CTP_BODY_TOO_LARGE`？

2.2 自定义错误 + `setErrorHandler`

3.2 通过 `CONFIG`/`CLI` 暴露配置

4.2 在 `onClose` 释放资源

Q2: 请求体过大报 `FST_ERR_CTP_BODY_TOO_LARGE`？