环境变量、配置管理、日志与统一异常处理
🎯 引言
学完这篇文章,你能通过环境变量配置端口,自动记录接口访问日志,并按请求编号排查异常。
⚙️ 启动时读取配置
新建 config.mjs,读取端口并检查范围:
const port = Number(process.env.PORT ?? 3000);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new Error('PORT 必须是 1 到 65535 的整数');
}
export const config = { port };
缺少 PORT 时使用 3000,写成 abc 会停止启动。数据库地址和密钥等必需配置应检查缺失,不能随意设置可公开的默认秘密值。
本地 .env 可以写入:
PORT=3000
使用 node --env-file=.env 启动时加载它,真实凭据不提交仓库。部署平台也可以直接注入环境变量。
📝 用日志中间件记录请求
pino-http 是请求日志中间件,会记录响应状态和耗时:
npm install pino-http@11.0.0
新建 logging-app.mjs:
import express from 'express';
import pinoHttp from 'pino-http';
import { randomUUID } from 'node:crypto';
export const app = express();
在路由前挂载日志中间件:
app.use(pinoHttp({
genReqId: () => randomUUID(),
redact: ['req.headers', 'req.url', 'req.query', 'req.params', 'res.headers'],
customProps: req => ({ path: req.path })
}));
genReqId 为请求生成编号。redact 隐去完整头部、URL 和参数,避免记录 Cookie、Authorization 或 Query 中的秘密;path 单独记录不含查询参数的路径。默认不会记录请求正文,不要自行把密码表单写进日志。
🏷 把请求编号返回客户端
继续添加:
app.use((req, res, next) => {
res.setHeader('X-Request-Id', req.id);
next();
});
前端报告问题时可以提供响应头中的编号,服务端按相同编号查日志。跨域页面若要通过脚本读取这个头,还需要在 cors 的 exposedHeaders 配置中允许 X-Request-Id。
🧯 记录异常并返回有限信息
先添加两个接口,一个成功,一个用于检查失败路径:
app.get('/health', (req, res) => res.json({ status: 'ok' }));
app.get('/failure', async (req, res) => {
throw new Error('模拟内部操作失败');
});
在它们后面配置错误处理中间件:
app.use((error, req, res, next) => {
if (res.headersSent) return next(error);
req.log.error({ err: error }, '请求处理失败');
res.status(500).json({ error: '服务暂时无法处理请求' });
});
req.log 自动关联当前请求,客户端只收到通用提示,服务端可以查看内部错误。需要同时处理 JSON 等输入错误时,把这条日志调用放进统一异常篇对应的错误分支,不要重复挂载多个会发送响应的错误处理器。
🚀 用配置启动并核对日志
新建 logging-server.mjs:
import { app } from './logging-app.mjs';
import { config } from './config.mjs';
app.listen(config.port, '127.0.0.1');
运行:
node --env-file=.env logging-server.mjs
请求 /health 得到 200,终端打印访问日志,其中包含状态与耗时。请求 /failure 得到 500,响应头编号与错误日志中的请求编号一致。日志耗时描述服务端处理时间,不是页面从点击到渲染结束的总时间。
❓ 知识问答
Q1:把全部请求内容记下来更方便吗?
可能泄露密码和令牌。记录排查必需的字段,并控制日志访问权限与保留期限。
Q2:每个业务函数都要记录一次错误吗?
不必。同一异常在最终处理位置记录,避免重复。
Q3:生产环境必须保存 .env 文件吗?
不必,部署平台注入的环境变量也能通过 process.env 读取。
🧪 小练习
将 PORT 改成 abc,确认启动失败;恢复后请求 /failure,核对响应编号和错误日志。
// 请在这里记录结果
