花了几天时间我把自学 Node.js 时的那些弯路挨个又走了一遍。如果你正打算入门或用它搭一个自己的小服务这篇东西应该能帮你省掉不少瞎折腾的时间。我一直觉得Node.js 最让人迷惑的不是 API 多复杂而是它跟传统后端语言完全不同的运行方式和工程习惯。这篇教程里我会从装好环境开始一步步写一个能真实跑起来的静态资源服务再走一遍模块机制、调试方法、部署时容易踩的坑全部基于实际可复现的操作。1. 环境准备与项目初始化别急着敲代码1.1 版本选择与安装方式Node.js 的版本号分成偶数 LTS 版和奇数 Current 版具体规则不复杂官方每年发布两个大版本四月和十月各一次。偶数版本比如 18、20、22会被标记为 LTS也就是长期支持版稳定维护时间能到三年左右奇数版本比如 19、21 这些是新功能试验场支持周期只有一年。我个人建议本地开发和服务器部署统一用 LTS 版本千万别追新。之前帮某开发者排查过一次线上事故他图新鲜装了当时最新的奇数版本结果某个依赖包里用了新特性其他同事的旧版本 Node 怎么都跑不起来最后整个项目被迫锁版本。这种事特别折腾没必要。安装方式上去官网下载绿色的 LTS 安装包Windows 和 macOS 直接下一步到底就能用Linux 的话建议通过包管理器安装。不过这里要重点说一句如果你打算长期做 Node.js 开发强烈推荐用 nvm 这类版本管理器来装不要用系统安装包。原因很简单Node 生态里不同工具、不同项目对版本要求差异不小今天这个项目要 16明天那个要 20用 nvm 一条命令就能随便切。# 安装 nvm 之后以 macOS/Linux 为例 nvm install --lts nvm use --lts node -v npm -v我自己经历过一个很尴尬的场面照着网上老教程用系统包管理器装好了 Node后来遇到一个项目脚本必须用新版本又不想动系统里已有的旧环境只能再补装 nvm把两套环境理清楚花了不少时间。有那功夫一开始直接用 nvm 早就省心了。1.2 用 npm init 生成项目骨架环境搞定以后新建一个目录来放项目然后执行初始化命令mkdir my-node-app cd my-node-app npm init -y这条命令会在当前目录生成一个package.json文件它是整个项目的“身份证”和“购物清单”。刚初始化出来的内容里有几个字段值得你花 10 分钟理解清楚后面实际开发中天天要跟它打交道main应用的入口文件路径默认是index.js。如果我自己写项目习惯把入口改成src/server.js目录结构更清晰。scripts自定义命令行指令的地方。可以放start: node src/server.js、dev: node --watch src/server.js这类懒人指令运行项目只要npm run dev就好。dependencies生产环境要用的依赖包列表。devDependencies只在本地开发调试时用的工具包比如测试框架、代码格式化工具。npm init -y里的-y是跳过交互式问答的快捷参数如果是给公司项目生成骨架还是建议去掉这个参数按提示一个个看清楚再填尤其是项目名和版本号以后发包或者安装依赖的时候常会用到。1.3 npm 镜像源与依赖安装细节国内直连 npm 官方源安装依赖时会慢到让人怀疑人生。这个问题的解法很成熟就是把 registry 换成国内速度更快的镜像源npm config get registry npm config set registry https://registry.npmmirror.com用第一条命令能看到当前源地址第二条是切换成国内镜像。我用这套配置很多年了安装大包基本秒下。但这里有个实际的坑想提醒你有些小工具包发布得比较频繁镜像源同步会有些延迟碰到最新版本装不上或者装下来行为不对时不用慌先把 registry 临时切回官方源再装一次大概率就好了。# 临时用官方源安装某个包 npm install --registryhttps://registry.npmjs.org some-package安装依赖时区分--save-dev简写-D和默认保存到dependencies的逻辑也很关键。规则只有一条运行项目本身必须的放 dependencies只有开发时期才用的放 devDependencies。比如 Express 框架要在生产环境里跑装成 dependencieseslint 是规范代码质量的工具上线后根本不需要装成 devDependencies 即可。装完依赖你会发现目录里多了个package-lock.json文件。这个文件务必提交到代码仓库里不要加到.gitignore。它的作用是锁定每个依赖包的精确版本哪怕某天包作者发布了有问题的新版只要拿着旧的 lock 文件重新npm install全家桶还按原来版本装项目还是能正常跑起来。不提交它的话同事拉代码后各自装出来的依赖可能都不一样到时候我机器上明明能跑这种现场翻车就来了。2. 模块机制从 CommonJS 到 ESM 的转变2.1 require 的加载规则与缓存问题Node.js 当初让不少写 JavaScript 的前端开发者最懵的就是require这套模块系统。它是历史沿革留下的产物即 CommonJS 规范。用法很简单一个文件就是独立模块通过module.exports向外暴露内容由require引入。// my-utils.js module.exports { add(a, b) { return a b; }, }; // main.js const utils require(./my-utils); console.log(utils.add(1, 2));这里有个很小的设计细节不太起眼但每回都能当成聊天素材讲文件末尾写module.exports和exports本质上是同一个对象。别直接给exports重新赋值比如exports { add() {} }这会把变量指到别处原来那个模块出口反而没变引入方拿到的是空对象。// 推荐写法 module.exports { add(a, b) { return a b; }, }; // 不推荐的写法很容易写出 bug exports { add(a, b) { return a b; }, };再聊一个更隐蔽的缓存机制。require不只是去磁盘读文件第一次加载一个模块时会把它执行一遍然后把结果存进内部缓存里之后再require同一个路径直接拿缓存不会重新执行。这个机制带来的直接后果是如果你在模块里维护了一份全局状态比如一段配置数据第一次require时被改动了第二次再require拿到的还是改过的旧缓存不是重新初始化后的干净数据。当年排查过好几次诡异的 bug都是以为每次require都能拿到全新副本其实吃的是缓存里的同一份对象。这里推荐的做法是把共享状态放在一个单独的模块里导出谁想改数据就通过这个模块的方法去改而不是在各处直接乱动导出对象的属性。2.2 循环引用常见但多数时候不用慌两个文件互相 require 对方这在小型项目里很常见。我见过不少人一碰到循环引用就吓得不行其实 Node 内部有处理策略遇到还没执行完的模块会返回一个不完整的导出对象而不是直接抛异常。// a.js const b require(./b); console.log(a.js 执行b 的导出, b); module.exports { name: A }; // b.js const a require(./a); console.log(b.js 执行a 的导出, a); module.exports { name: B };跑node a.js你会观察到b.js 执行时拿到的 a 是一个空对象因为 a.js 的导出还没执行完且 require 判断到它在环里就先返回一个不完整的状态。这其实是设计上的容错不是越界 bug。真正应该做的是避免在模块顶层互相依赖形成环。真要出现环多半是设计上有职责边界不明的问题。最简单可靠的解法是抽一个公共模块把互相依赖的东西下沉到那个模块里让环变成单向引用。延迟加载也是一个办法把require函数调用放到函数内部而不是文件顶部等到运行时再引用模块就不会撞上顶层环的问题。2.3 ESM 模块系统与 Node 里的共存现状前端圈现在早就全面拥抱 ESMimport/export了Node 这边也早已原生支持// 文件后缀换成 .mjs或 package.json 中设置 type: module import { add } from ./my-utils.mjs; console.log(add(3, 5));Node 判断文件到底属于 CommonJS 还是 ESM有一套明确的规则不搞清楚是要踩坑的文件后缀为.mjs强制按 ESM 解析。文件后缀为.cjs强制按 CommonJS 解析。.js文件看 package.json 里的type字段默认是commonjs设置成module就按 ESM。实际开发里最烦的是混着用。比如项目是 CommonJS 写的想动态引入一个新写的 ESM 模块直接require会报错因为这俩机制在 Node 里是不直接互通的。我的建议是新项目直接用 ESM也就是把 package.json 里写上type: module老项目保持 CommonJS别中途强行翻新。真要新旧模块共存我会用await import()这种动态导入语法在 CommonJS 文件里加载 ESM 模块运行时是可行的比改一堆文件后缀来得稳。3. 核心 API 实操从零写一个静态资源服务器3.1 用 http 模块起底服务器原理很多教程一上来就用 Express导致很多人压根不知道 Node.js 自带的能力有多强。我建议每位入门者都亲手用原生http模块写一个服务器哪怕只跑通一次之后读任何框架源码都能脑补出它们底层在做什么。创建server.js写入以下代码const http require(http); const hostname 127.0.0.1; const port 3000; const server http.createServer((req, res) { res.statusCode 200; res.setHeader(Content-Type, text/plain; charsetutf-8); res.end(Hello, Node.js!\n); }); server.listen(port, hostname, () { console.log(服务器运行在 http://${hostname}:${port}/); });终端里执行node server.js浏览器打开http://127.0.0.1:3000就能看到Hello, Node.js!。看懂这几行代码就够了其余全是它的延伸http.createServer里传的回调函数在每次收到请求时被触发回调里req请求和res响应两个对象就是和客户端对话的全部窗口。理解了这一点后续用 Express 时你就会明白所谓框架不过是对这两个对象做了一层封装。但是这里只做了一次基础握手远远不够。真实场景里要处理路由、静态文件、请求体解析、异常处理。我为什么会建议先手写原生 API因为一旦能凭自己写出不带框架的服务器你再去理解 Express 里的中间件、路由表设计会舒服很多。很多人一上来就封装好的框架出了问题面对的是多层抽象很难定位到真正源头在哪。3.2 路由分发理解 URL 到代码的映射所谓路由就是把 URL 路径对应到具体处理函数。原生 http 里没有现成的路由表需要自己从req.url里解析出来。const http require(http); const server http.createServer((req, res) { const { pathname } new URL(req.url, http://${req.headers.host}); console.log(请求路径:, pathname); if (pathname /) { res.writeHead(200, { Content-Type: text/html; charsetutf-8 }); res.end(h1首页/h1); return; } if (pathname /about) { res.writeHead(200, { Content-Type: text/html; charsetutf-8 }); res.end(h1关于页面/h1); return; } res.writeHead(404, { Content-Type: text/html; charsetutf-8 }); res.end(h1页面不存在/h1); }); server.listen(3000);这里要注意是用URL这个类去解析路径而不是直接对req.url做字符串切割。因为req.url里可能包含了查询参数比如/about?fromhome直接匹配字符串会拿不到期望结果用new URL(req.url, base)构造后取pathname就能把路径和参数干净地拆开。写得再清楚一点路由本质上就是条件判断 业务函数的组合核心逻辑不复杂。小型项目里几个 if 完全够用但请求路径一多if else 就会膨胀那时可以考虑如下方式先按路径做一层映射表再匹配对应的回调函数。不过别过度设计真正需要框架时再上框架不迟。3.3 用 fs 模块读取真实文件静态资源服务路由只返回写死的 HTML 显然不实用真实网站要读磁盘上的文件返回给浏览器。这时就要引入 Node.js 的fs模块和path模块。const http require(http); const fs require(fs); const path require(path); const server http.createServer((req, res) { const { pathname } new URL(req.url, http://${req.headers.host}); // 简单映射把 / 指向 index.html let filePath pathname / ? /index.html : pathname; filePath path.join(__dirname, public, filePath); fs.readFile(filePath, (err, data) { if (err) { res.writeHead(404, { Content-Type: text/plain; charsetutf-8 }); res.end(404 Not Found); return; } res.writeHead(200, { Content-Type: text/html; charsetutf-8 }); res.end(data); }); }); server.listen(3000);这个朴素版本能跑但实际用的时候有几个问题必须注意。第一是不要用字符串拼接文件路径。我见过不少初学的人这么干./public req.url赶上 URL 里带..这种双点跳转的请求用户很可能直接访问到服务器上/public之外的敏感文件这就是经典的路径遍历安全漏洞。用path.join也不是绝对安全真实还应该拿到完整路径后检查是否还在允许的根目录内。第二是 MIME 类型问题。上面代码统一返回text/html但如果是图片、CSS、JS 文件浏览器可能无法正确渲染。完整的静态服务得按文件扩展名输出对应的 MIME 类型比如.css对应text/css、.js对应application/javascript、.png对应image/png。const mimeTypes { .html: text/html; charsetutf-8, .css: text/css; charsetutf-8, .js: application/javascript; charsetutf-8, .json: application/json; charsetutf-8, .png: image/png, .jpg: image/jpeg, }; const ext path.extname(filePath).toLowerCase(); const contentType mimeTypes[ext] || application/octet-stream;第三理想情况下应该用fs.createReadStream而不是fs.readFile。前者是流式读取适合大文件内存占用稳定后者会把整个文件一次性读进内存大文件读写多了内存很容易飙上去。这个细节在压力测试时特别明显初次接触 Node 就能建立这个概念后面写文件上传下载功能会少走很多弯路。3.4 引入 Express 的时机与理由手写实现了路由解析和静态文件读取后再来看 Express 提供的三样核心价值就很容易理解了路由中间件体系不用自己写 if else 做分发app.get(/about, handler)更直观。内置静态资源中间件express.static(public)帮你处理好了路径安全、MIME 类型、缓存头这些问题。更大的生态写接口时用的req.body解析、文件上传、Cookie 处理都有现成中间件。但我的观点一直很明确别一上来就用 Express。先用原生 API 写一遍最简单的服务和接口认清req、res、http、fs这些地基模块是干嘛的再切到框架会顺畅很多。这就跟在工地先学会搬砖再碰吊车一个道理不是为了炫技是为了出事时你心里有底就算框架再薄也不会慌到不知道错误出自哪一层。等你对 Express 已经很熟了再回头看手写的日子会理解框架为什么这样设计以及某些性能瓶颈在底层可能出在哪儿。4. 调试、错误处理与开发效率提升4.1 正确处理未捕获异常与 Promise rejectionNode.js 里有一类经典问题就是程序一遇到异常直接崩溃退出常见的元凶是顶层的未捕获异常和未处理的 Promise rejection。Node 默认策略很硬核异常没人接进程就退绝不含糊。process.on(uncaughtException, (err) { console.error(未捕获异常:, err); // 记录日志、尝试清理、然后决定是否退出 }); process.on(unhandledRejection, (reason, promise) { console.error(未处理的 Promise rejection:, reason); });直白说注册这两个监听器是保底方案不是让你随意吞掉问题。最忌讳的是只要监听了就让进程继续跑也不记录、不分析这会让服务带着脏状态运行后续行为完全不可预测。我的经验是顶层的uncaughtException和unhandledRejection监听器主要负责留遗言——把这个错误完整地记到日志文件或上报系统里然后主动process.exit(1)让进程管理器把它重启起来。真正的健壮性要靠每一层业务代码自己做好 try/catch而不是指望兜底机制帮忙续命。业务代码里最推荐的错误处理姿势是async function getUserById(id) { if (!id) { throw new Error(id 不能为空); } const user await db.findUser(id); if (!user) { throw new Error(用户不存在); } return user; }把错误在发生的源头抛出来由上层调用方决定怎么响应——是返回 400 给前端还是记录日志后返回 500。这样的错误蔓延方向清晰排查问题的时候顺着错误栈一路找下去基本都是通畅的。4.2 内置调试工具node --watch 与 --inspect早期写 Node 最烦躁的一点是改动代码后得手动重启进程才能看到变化。官方后来内置了node --watch参数解决了这个痛点node --watch server.js它会监听执行文件本身以及它依赖的模块文件一变自动重启。早期这个功能需要装第三方工具 nodemon现在内置后我日常开发基本不再额外装 nodemon 了。如果遇到更复杂的调试场景node --inspect是真香。启动方式node --inspect9229 server.js然后打开 Chrome 浏览器地址栏输入chrome://inspect就能把 Node 进程关联到 DevTools 界面像调试前端代码一样打断点、看调用栈、查看变量还可以在 Sources 面板里实时改代码。这个方法比满屏打console.log不知道高效多少倍。如果只是想快速查看某个变量或函数的返回值可以用node -e在命令行里执行表达式node -e console.log(JSON.stringify({ a: 1, b: 2 }))这个场景适合验证小段逻辑或查看模块输出比自己写个临时文件再跑省事得多。4.3 用好 console 的差异化输出别小看console这个全局对象实际工程里它承担了绝大多数日志定位工作。我专职排查线上问题时列过一套自己的输出规范普通状态console.log(服务已启动端口, port)警告console.warn(配置项缺失使用默认值, defaultValue)严重错误console.error(数据库连接失败, err)这类输出通常带完整错误对象和堆栈。调试变量console.log({ userId, orderId })用对象字面量包一层变量名能在日志里直接看到变量名和值不用猜。还有一个实用技巧写日志时别只打印一行字尽量把上下文的关联信息带上。比如console.error(查询订单失败, { orderId, error: err.message })将来你在日志平台上搜索时能直接从关键字搜到这批关联信息定位速度完全不同。4.4 把调试信息可视化错误栈与 source map线上 Node 服务常见的坑之一就是错误堆栈指向的是压缩或编译后的代码根本看不出是哪行业务代码出的问题。如果项目里用了 TypeScript、Babel 这类转译工具记得生成并保留 source map并在部署时同步上传排查问题时就能把错误位置映射回真实源码。具体来说用 TypeScript 编译时在tsconfig.json里设置sourceMap: true启动脚本里用node --enable-source-maps server.jsNode 在输出错误堆栈时会自动使用 source map 还原出原始文件路径与行号。这个设置在项目中有没有都可能不影响功能但一旦线上出现疑难问题有这么一份映射表排查效率天差地别。我吃过不少没有 source map 的亏对着压缩后的代码一个个变量猜含义极其痛苦。5. 部署与维护中的现实问题5.1 环境变量永远不要硬编码配置部署到服务器上跟本地跑最大的不同就是配置不再藏在代码里。数据库密码、API 密钥、监听端口这些一旦写死在代码里要么被提交到仓库泄漏要么换个环境就要改代码重新上线非常不专业。Node.js 提供process.env直接把运行环境里的变量暴露给代码PORT8080 NODE_ENVproduction node server.jsconst port process.env.PORT || 3000; const isProd process.env.NODE_ENV production; if (!process.env.DATABASE_URL) { console.error(缺少 DATABASE_URL 环境变量); process.exit(1); }用上默认值和启动时校验是习惯问题但这几个习惯能直接拦住特别大的一类配置事故。NODE_ENV这个变量在 Node 生态里有特殊地位不少框架会按它的值决定加载哪些依赖、打印哪些日志。生产环境务必显式设置成production没有设置时很多包默认按开发模式加载性能和日志行为都不一样。要更规范地管理本地开发的环境变量可以引入dotenv库它会把根目录下.env文件里的键值对加载到process.env中npm install dotenv项目根目录创建.envPORT8080 DATABASE_URLmysql://user:passlocalhost/dbname然后在入口文件最前面引入require(dotenv).config(); const port process.env.PORT || 3000;关键警告.env文件务必加入.gitignore绝不允许提交到代码仓库。公钥私钥另说数据库密码、API 密钥一旦上仓库就是安全事故。每个环境各有一份.env部署时单独配置这套方式简单可靠且应用非常广。5.2 进程守护PM2 的 fork 与 clusterNode 应用跑在服务器上单靠node server.js是很脆弱的进程一挂就没人管开机也不会自启。生产环境我首选进程守护工具 PM2。PM2 的安装和使用十分简单npm install -g pm2 pm2 start server.js --name my-app pm2 logs my-app pm2 restart my-app pm2 stop my-app pm2 delete my-app pm2 savesava命令也很重要它会把当前运行的进程列表保存下来配合pm2 startup设置开机自启服服帖帖的。PM2 还内置 cluster 模式可以用一台机器的多个 CPU 核心拉起多个进程实例分发请求pm2 start server.js -i max-i max表示按 CPU 核心数创建进程实例每个实例共享同一个端口由 PM2 做负载均衡。这对 Node 这种单线程运行模式的服务来说是提升吞吐量最直接的手段。但我必须提醒一个 cluster 模式下容易踩的坑如果应用内部维护了内存态的会话数据或缓存-i max拉起多个进程后A 进程里存的用户登录状态B 进程里并没有。用户在两次请求之间被分到不同进程就会莫名跳出登录或状态丢失。要顺利跑 cluster 模式应用的状态必须设计成无状态或者把共享数据放到 Redis 这一类的独立存储中而不是藏在进程内存里。5.3 依赖安全npm audit 不是摆设依赖包引进来只是第一步它们的安全隐患也需要持续关注。npm audit是内置的检查命令npm audit npm audit fix npm audit fix --forcenpm audit会把 package-lock.json 里锁定的版本拿去和漏洞库比对输出风险等级和受影响包名。一般做法是npm audit fix能修的小漏洞直接修大版本变动需要谨慎评估不要无脑--force因为自动升大版本可能带来破坏性变更让代码直接编译不过。我建议把npm audit纳入日常流程比如每星期抽时间跑一次或者把它写进 CI 流水线里在发布前自动检查高危漏洞。此外一个不怎么起眼但值得养成的习惯安装新包前看一眼这个包的周下载量和最近更新时间。周下载量几百上千的包一旦出问题可能根本没人维护风险非常大。正经大型项目用到的核心包基本都有较高的社区使用量这类包往往修复漏洞也及时。5.4 用 Node 原生测试框架做基础回归很多 Node 入门者会把写测试当成大公司才做的事但从我自己的经历来看一个能跑的简单测试能在重构和升级依赖时替你挡住太多意外。Node 18 以后内置了测试运行器node:test不需要额外装测试框架就能写const { test } require(node:test); const assert require(node:assert); function add(a, b) { return a b; } test(add 函数能正确相加, () { assert.strictEqual(add(1, 2), 3); assert.strictEqual(add(-1, -1), -2); });运行方式node --test它会自动识别测试文件并执行。如果你项目规模不大原生测试框架基本够用等测试量涨到几百上千再考虑 Jest、Vitest 这类功能更丰富的测试框架也不迟。自动化测试的意义不用多说每次改动代码后跑一遍整个测试集能在几秒内发现改坏了什么这比上线后用户帮你发现 bug 强了不知道多少倍。写在最后保持简单然后逐步演进完整的 Node.js 知识体系远不止上面这些内容但我觉得把上面几块理清楚你已经具备独立做一个可上线项目的底子会装环境、会初始化项目、理解模块系统、能用原生 API 写服务也知道了如何处理错误、守卫生产配置与做基础测试。Node.js 的魅力在于它足够轻不需要太沉重的工具链就能做出东西来但它又足够深深到你可以在任何一个方向继续钻研比如事件循环机制、流式处理、底层 addon 等等。我自己在实际操作中的体会是入门阶段最重要的不是把 API 背全而是亲手把一个真实的小项目从零写到部署让整条链路在脑子里完整跑通。遇到不懂的先查文档百度文档有时候质量参差不齐直接看官方文档或源码反而更清晰。踩坑不可怕可怕的是踩完坑不知道为什么踩。如果你正卡在某一步建议把上面的代码自己敲一遍再改几个参数观察结果。Node.js 的开发体验真正顺畅起来是在你建立了报错信息是可以被理解的这个信念之后。希望这篇教程能帮你少走一段弯路更早写出能跑、能上线、也能维护的小服务。