在 Debian 上开发和部署 Node.js 应用时，日志不是简单“打几行字”那么轻。开发阶段要快速定位代码走向，生产环境又要兼顾性能、持久化、集中管理和磁盘占用。本文按实际排查路径，把基础日志、日志库、环境变量控制、调试工具、日志轮转和系统日志查看串成一套完整做法，方便你根据场景判断该用哪一层、怎么组合更合适。
为什么要把日志链路分层处理
Node.js 在 Debian 上运行时，日志通常会经历几个阶段：开发时先看终端输出，问题变复杂后写入文件，项目规模扩大后再接入日志库和系统日志，最终还要考虑轮转与统一检索。把这些能力分层处理，能避免前期过度设计，也能减少后期排障时“日志不够看”或“日志太难找”的问题。
下面的内容按使用频率和落地难度递进展开，命令、配置和代码示例均可直接作为参考。
先从基础日志做起：终端输出与文件落盘
用 console.log / console.error 快速打点
排查接口是否命中、变量值是否正确、启动流程是否执行到位，最直接的方式仍然是 console.log。而 console.error 更适合在异常捕获后输出错误堆栈，便于第一时间定位问题。
这类方式胜在简单，但更适合开发阶段。到了生产环境，如果高频请求都直接写标准输出，I/O 成本会逐渐放大，不建议长期作为主方案。
const express = require('express');
const app = express();
app.get('/', (req, res) => {
console.log('Received request at /'); // 记录请求到达
res.send('Hello World!');
});
app.listen(3000, () => {
console.log('Server running on port 3000'); // 记录服务启动
});把日志写入文件，解决持久化问题
当终端输出越来越多，仅靠滚屏查找已经不够用。这时更稳妥的做法是把日志写入文件，至少保证信息可以回看、检索和归档。
Node.js 自带的 fs 模块就能完成这件事。简单场景可以用 fs.appendFile，而持续写入更适合使用 fs.createWriteStream。
const fs = require('fs');
const logStream = fs.createWriteStream('app.log', { flags: 'a' }); // 追加模式
app.get('/data', (req, res) => {
const data = { timestamp: new Date(), status: 'success' };
logStream.write(JSON.stringify(data) + 'n'); // 写入JSON格式日志
res.json(data);
});如果后续还要做日志检索、分析或集中采集，尽量从一开始就采用结构化内容，例如 JSON 格式，这样后面接入 syslog、日志平台或脚本分析时更省事。
项目一大，优先换成专业日志库
当应用进入多人协作、接口增多或服务拆分阶段，手写日志往往很快会遇到几个问题：级别不好控、输出目标分散、格式不统一、后续分析困难。这个阶段更适合把日志能力交给专门的库。
Winston：功能全面，适合需要多输出目标的项目
Winston 的优势在于能力完整。它支持多个传输目标，可以同时输出到控制台、文件、数据库等位置；日志级别和格式化规则也比较灵活，适合中大型项目统一管理日志。
const winston = require('winston');
const logger = winston.createLogger({
level: 'debug', // 默认日志级别（开发环境设为debug，生产设为info）
format: winston.format.json(), // 输出JSON格式（便于后续分析）
transports: [
new winston.transports.Console({ format: winston.format.simple() }), // 控制台输出简单格式
new winston.transports.File({ filename: 'error.log', level: 'error' }), // 错误日志单独存储
new winston.transports.File({ filename: 'combined.log' }) // 所有日志合并存储
]
});
// 在代码中使用
logger.debug('Debug message: User logged in'); // 仅在debug级别生效
logger.error('Error: Database connection failed'); // 输出到error.log和控制台如果你需要“错误日志单独归档，同时保留全量日志”，Winston 这类多 transport 方案会比较顺手。
Pino：更看重性能时的常见选择
如果应用本身对吞吐和延迟更敏感，Pino 往往更合适。它的默认输出就是结构化 JSON，整体风格更轻量，尤其适合生产环境做高频日志记录。
const pino = require('pino');
const logger = pino({ level: 'info' }); // 默认级别为info
app.get('/api', (req, res) => {
logger.info({ req, response: 'OK' }, 'API request processed'); // 结构化日志（包含请求信息）
res.send('API response');
});如果你的重点是“尽量少影响线上性能，同时保留结构化日志能力”，Pino 通常比传统方案更适合作为默认选择。
把日志接入 Debian 的 syslog，便于集中管理
当一台 Debian 主机上跑着多个 Node.js 服务时，日志分散在不同目录会明显增加运维成本。把应用日志发送到 syslog 后，可以统一存储，再配合 journalctl 或系统级采集方案集中查看。
社区已经提供了对应插件，例如 winston-syslog 和 pino-syslog。下面是 winston-syslog 的示例：
const winston = require('winston');
require('winston-syslog').Syslog; // 引入syslog传输
const logger = winston.createLogger({
transports: [
new winston.transports.Syslog({
host: 'localhost', // syslog服务器地址（本地为localhost）
port: 514, // syslog默认端口
app_name: 'my-node-app', // 应用名称（在syslog中标识）
eol: 'n' // 行结束符
})
]
});
logger.info('This log is sent to syslog'); // 输出到系统日志这一层更适合有统一运维需求的环境，尤其是同机多服务、需要系统级检索或后续集中采集的场景。
用环境变量切换日志级别，避免改代码发版
开发环境通常需要尽量多的信息，生产环境则更关注 warn 和 error。如果每次切换都修改代码，不仅繁琐，也容易带来配置漂移。更常见的做法是通过环境变量控制日志级别。
直接在命令行指定
# 开发环境：显示所有日志（包括debug）
DEBUG=* node app.js
# 生产环境：仅显示error和warn
LOG_LEVEL=warn node app.js在代码里读取 process.env
把默认级别写在代码里、把实际级别交给环境变量，是最常见也最稳妥的方式。
const winston = require('winston');
const logger = winston.createLogger({
level: process.env.LOG_LEVEL || 'info', // 优先使用环境变量，未设置则默认为info
transports: [
new winston.transports.Console()
]
});配合 PM2 管理不同环境配置
如果项目由 PM2 托管，可以直接在 ecosystem.config.js 里区分开发和生产环境的日志级别。这样切换环境时只需要更换启动参数，不必再去改应用逻辑。
module.exports = {
apps: [{
name: 'my-app',
script: 'app.js',
env: {
NODE_ENV: 'development',
LOG_LEVEL: 'debug' // 开发环境开启debug日志
},
env_production: {
NODE_ENV: 'production',
LOG_LEVEL: 'error' // 生产环境仅记录error
}
}]
};启动命令：
pm2 start ecosystem.config.js --env production # 启动生产环境只看日志还不够时，用调试工具补足现场信息
日志更适合“记录发生过什么”，但遇到执行路径复杂、异步调用交错或变量状态不明确的问题时，单靠日志往往不够。这时应该结合调试器直接观察运行过程。
Node.js 内置调试器
Node.js 自带调试能力，可以通过 node inspect 启动。它支持断点、变量查看和调用栈跟踪，适合在终端环境下快速介入。
node inspect app.js # 启动调试模式常用命令包括：
cont：继续执行next：执行下一行step：进入函数内部repl：进入REPL模式（查看变量值）
Chrome DevTools 图形化调试
如果你更习惯图形界面，可以使用 --inspect 启动应用，再在浏览器中打开 chrome://inspect，进入 Node 专用开发工具进行调试。
node --inspect app.js这种方式更适合需要直观看调用栈、断点和变量面板的场景。
Visual Studio Code 一键调试
对于 VS Code 用户，直接配置 .vscode/launch.json 后按 F5 即可启动调试，适合日常开发中持续使用。
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Node.js",
"program": "${workspaceFolder}/app.js",
"console": "integratedTerminal", // 输出到VS Code终端
"sourceMaps": true // 支持sourcemap（若使用TypeScript）
}
]
}如果项目还用了 TypeScript，sourceMaps: true 会让断点和源码映射更准确。
别忽视日志轮转：避免日志文件无限膨胀
文件日志能解决持久化，但如果长期不清理，磁盘空间迟早会被占满。在 Debian 上，最常见的处理方式就是使用 logrotate 自动轮转日志。
安装 logrotate
sudo apt update
sudo apt install logrotate创建轮转配置文件
可以在 /etc/logrotate.d/ 下为 Node.js 应用单独创建规则文件：
sudo nano /etc/logrotate.d/nodejs内容示例：
/path/to/your/app/*.log { # 匹配日志文件路径（替换为实际路径）
daily # 每天轮转一次
missingok # 若日志文件不存在也不报错
rotate 7 # 保留最近7天的日志
compress # 压缩旧日志（使用gzip）
notifempty # 若日志为空则不轮转
create 0644 root root # 新日志文件的权限和所有者
}这里的几个关键项分别控制轮转频率、保留份数、压缩方式以及新文件权限。实际部署时，最需要确认的是日志路径和文件所属用户是否匹配当前服务。
先做一次测试再上线
配置写完后，建议先手动验证，避免正式轮转时才发现路径或权限问题。
sudo logrotate -d /etc/logrotate.d/nodejs # 干运行（不实际执行）
sudo logrotate -f /etc/logrotate.d/nodejs # 强制立即执行日志进了 syslog 之后，怎么用 journalctl 查看
如果应用日志已经接入 syslog，或者服务本身由 systemd 管理，那么 journalctl 就会成为最直接的查看入口。它是 Debian 常用的系统日志工具，适合按服务、按时间范围做排查。
查看全部系统日志
journalctl按服务名查看 Node.js 服务日志
如果应用通过 systemd 管理，例如结合 pm2-systemd 部署，可以直接按服务名过滤：
journalctl -u my-node-app.service # 替换为实际服务名称按时间范围过滤
journalctl --since "2025-09-25 00:00:00" --until "2025-09-25 23:59:59" # 查看当天日志这一类命令非常适合复盘故障窗口，例如“某次发布后到报警恢复前”的日志区间。
一条更实用的落地路径
如果你是从零搭建日志方案，通常可以按下面的顺序推进：
- 开发阶段先用
console.log/console.error快速定位流程问题。 - 开始需要回溯时，尽快把日志写入文件，并尽量使用 JSON 结构化格式。
- 项目进入稳定运行期后，优先切换到 Winston 或 Pino。
- 多服务共机部署时，再接入
syslog和journalctl做统一查看。 - 只要使用文件日志，就尽早配置
logrotate。 - 遇到复杂异步问题时，用
node inspect、--inspect或 VS Code 调试器补足日志看不到的现场。
这样做的好处是，每一层都能解决一个明确问题：日志有没有、能不能留、好不好管、查不查得到，以及会不会把磁盘写满。对 Debian 上的 Node.js 应用来说，这基本就是一套可持续使用的日志调试链路。
