Node.js入门指南：从环境搭建到核心概念与实战应用

1. 项目概述：为什么Node.js是前端开发的“第二把钥匙”？

如果你是一名前端开发者，可能已经习惯了在浏览器里用JavaScript写交互、调接口、做动画。但你是否想过，如果能让这门语言跳出浏览器的“舒适圈”，去操作文件、连接数据库、甚至搭建一个完整的服务器？这就是Node.js带给我们的能力。它不是一个全新的语言，而是让JavaScript运行在服务器端的一个运行时环境。简单来说，它让前端开发者用自己最熟悉的语言，去涉足后端开发的领域，实现从前到后的“全栈”能力。很多人觉得后端开发门槛高，要学Java、Python、Go，但Node.js的出现，让前端开发者能以极低的切换成本，构建起自己的后端服务。这篇文章的目的，就是帮你把这把“钥匙”稳稳地拿到手，从零开始，用最清晰、最详细的方式，带你快速入门Node.js，把基础打牢。我会按照核心要点来整理知识点，让你看完就能动手，而不是停留在概念层面。

2. 环境准备：从零搭建你的Node.js开发环境

任何技术的学习，第一步永远是搭建一个能跑起来的环境。对于Node.js来说，这一步尤其重要，因为它直接关系到后续所有命令和项目的运行。很多新手卡在第一步，就是因为环境没配好。

2.1 Node.js的安装与版本管理

首先，你需要安装Node.js。这里我强烈建议不要直接从官网下载安装包然后一路“下一步”就完事了。对于前端开发者，一个更优雅、更专业的做法是使用Node版本管理器（Node Version Manager, NVM）。

为什么用NVM？想象一下，你手头可能同时维护着两个项目：一个老项目用的是Node.js 14，另一个新项目要求Node.js 18。如果你只安装了其中一个版本，切换起来会非常麻烦，需要反复卸载重装。NVM就是为了解决这个问题而生的，它允许你在同一台机器上安装并切换多个Node.js版本，就像给你的电脑装了一个“版本开关”。

Windows系统安装NVM对于Windows用户，推荐使用nvm-windows。这是社区维护的版本，非常稳定。

1. 卸载现有Node.js：如果你之前通过安装包装过Node.js，请先到控制面板的程序卸载功能里把它卸载干净，避免冲突。
2. 下载安装包：访问nvm-windows的GitHub发布页面，下载最新的安装程序（通常是nvm-setup.exe）。
3. 安装过程：运行安装程序。安装路径可以保持默认（例如C:\Users\你的用户名\AppData\Roaming\nvm），这个路径后续会用来存放不同版本的Node.js。安装程序会自动帮你配置系统环境变量。
4. 验证安装：打开一个新的命令行窗口（CMD或PowerShell），输入nvm version。如果能看到版本号，说明安装成功。

macOS/Linux系统安装NVM对于macOS或Linux用户，安装更简单，通过终端命令即可完成。通常使用curl或wget下载安装脚本。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

或者

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，关闭并重新打开终端，或者执行source ~/.bashrc（或source ~/.zshrc，取决于你用的shell）使配置生效。然后输入nvm --version验证。

使用NVM安装和管理Node.js安装好NVM后，安装Node.js就变得非常简单。

• 查看可用版本：nvm list available会列出所有可安装的远程版本。
• 安装指定版本：比如安装最新的长期支持版（LTS），命令是nvm install 18.19.0（版本号以当时最新LTS为准）。NVM会自动下载并安装。
• 安装最新版：nvm install latest。
• 查看已安装版本：nvm list或nvm ls。
• 切换使用版本：nvm use 18.19.0。这个切换是临时的，只对当前命令行窗口生效。
• 设置默认版本：nvm alias default 18.19.0。这样每次新开终端都会自动使用这个版本。

注意：在Windows PowerShell中执行npm脚本时，可能会遇到“无法加载文件...因为在此系统上禁止运行脚本”的错误。这是因为PowerShell的执行策略限制。解决方法是以管理员身份打开PowerShell，执行Set-ExecutionPolicy RemoteSigned，然后选择Y。这是一个安全策略调整，允许运行本地签名的脚本。

2.2 验证安装与理解核心组件

安装完成后，我们需要验证Node.js是否真的可以用了，并理解我们到底安装了些什么。

打开你的命令行（终端、CMD、PowerShell等），依次输入以下命令：

node -v npm -v

如果分别输出了Node.js和npm的版本号，比如v18.19.0和10.2.3，那么恭喜你，环境安装成功了！

Node.js：这就是我们安装的运行时本身。node -v查看的是Node.js解释器的版本。

npm (Node Package Manager)：这是随Node.js一同安装的包管理工具，它是Node.js生态的基石。你可以把它想象成前端的“应用商店”或“软件仓库”。全世界数百万的开发者将自己写的可复用代码模块（称为“包”或“package”）发布到npm的公共仓库。当你开发项目时，如果需要某个功能（比如处理时间的moment库，或者Web框架express），不需要自己从头写，只需要通过npm一条命令就能安装到自己的项目中。npm -v查看的就是这个包管理工具的版本。

npx：这也是一个很实用的工具，它允许你直接运行本地或远程npm包中的命令，而无需先全局安装这个包。例如，有些脚手架工具，你只需要临时用一次，用npx就非常方便。

至此，你的开发环境已经就绪。有了Node.js和npm，你就拥有了进入整个Node.js庞大生态系统的门票。

3. Node.js核心概念与运行机制深度解析

在开始写代码之前，我们必须先理解Node.js的几个核心设计思想。这能帮你从根上明白，为什么它适合某些场景，而在另一些场景下可能不是最佳选择。

3.1 事件驱动与非阻塞I/O：高并发的秘密武器

这是Node.js最著名、也最容易被误解的特性。我们用一个生活中的例子来类比。

传统多线程/多进程模型（阻塞I/O）：想象一家只有一位厨师的餐厅（服务器）。来了5位客人（5个请求），点了不同的菜。厨师只能一道一道做。做第一道菜时，后面4位客人只能干等着，即使他们点的菜很简单。这就是“阻塞”，一个慢请求会卡住所有后续请求。为了解决这个问题，餐厅（服务器）会雇佣多个厨师（多线程/多进程），每个厨师服务一位客人。但这带来了新的问题：厨师（线程）成本高（占用大量内存），厨师间协调复杂（线程同步、锁），人多了厨房还挤（上下文切换开销大）。

Node.js事件驱动模型（非阻塞I/O）：还是那位厨师，但他现在是个“事件驱动”的超级厨师。5位客人点完菜，厨师不是立刻开始做，而是把每道菜需要做的事情（洗菜、切菜、烧水、炖煮）拆分成一个个极小的“任务”，并记在小本本（事件队列）上。然后他开始处理第一个任务（比如给所有菜烧上水）。在烧水等待的这几分钟里，他并不会闲着等水开，而是立刻去处理小本本上的下一个任务（比如切第一道菜的配菜）。当水烧开的“事件”发生时（可能是由另一个系统“回调”通知他），他再回来进行下一步操作（放入食材）。这样，在I/O操作（烧水、炖煮等需要等待的操作）进行时，厨师（主线程）的CPU时间并没有被浪费，而是去处理其他任务了。

在Node.js中，这个“超级厨师”就是单线程的V8 JavaScript引擎。那个“小本本”就是事件队列（Event Queue）。而那个处理事件、调度任务的机制，就是事件循环（Event Loop）。所有耗时的I/O操作（如读写文件、网络请求、数据库查询）都不会阻塞主线程，而是提交给系统底层（由C++实现的libuv库）去执行。当底层操作完成时，会生成一个“完成事件”并附带结果，这个事件和对应的回调函数会被放入事件队列。事件循环会不断地从队列中取出事件并执行对应的回调函数。

带来的好处：对于I/O密集型的应用（比如Web服务器，大部分时间在等待网络响应和数据库查询），这种模型能用很少的系统资源（一个主线程）支撑非常高的并发连接。因为它没有线程创建和切换的开销。

需要注意的坑：正因为是单线程，如果你在回调函数里执行了非常耗时的CPU密集型操作（比如复杂的数学计算、大规模数据循环处理），那么事件循环就会被这个操作阻塞，期间所有新来的事件都无法被处理，整个服务器就会“卡住”。这是Node.js的软肋。解决方案是：将这类耗时任务交给工作线程（Worker Threads）或者拆分成更小的异步任务。

3.2 模块系统：代码组织的基石

在浏览器中，我们通过<script>标签引入JS文件，全局变量容易污染。Node.js采用模块化来组织代码，一个文件就是一个模块，模块内的变量、函数默认是私有的，不会影响到其他模块。

CommonJS模块：这是Node.js原生支持的模块规范，使用require导入，module.exports或exports导出。

// calculator.js - 定义一个模块 function add(a, b) { return a + b; } function subtract(a, b) { return a - b; } // 导出方式一：导出一个对象 module.exports = { add, subtract }; // 导出方式二：逐个附加到 exports 上 // exports.add = add; // exports.subtract = subtract; // app.js - 使用模块 const calc = require('./calculator.js'); // 注意路径 console.log(calc.add(5, 3)); // 输出 8

require是同步加载模块，这符合Node.js最初服务端脚本的定位。

ES Modules (ESM)：这是ECMAScript标准的模块系统，使用import和export语法。现在Node.js也提供了支持。

// calculator.mjs 或 package.json 中设置 "type": "module" export function add(a, b) { return a + b; } export function subtract(a, b) { return a - b; } // app.mjs import { add, subtract } from './calculator.mjs'; console.log(add(5, 3));

要使用ESM，文件后缀需改为.mjs，或者在package.json中设置"type": "module"。ESM是异步加载的，是未来的趋势，但在Node.js生态中，CommonJS目前仍占主流，很多老包只支持CommonJS。混用时需要特别注意。

核心模块与第三方模块：Node.js自带了很多核心模块，如fs（文件系统）、http（网络）、path（路径处理），无需安装，直接require即可。第三方模块就是通过npm安装的包。

3.3 包管理：npm与package.json

package.json文件是Node.js项目的“身份证”和“说明书”，它位于项目的根目录，记录了项目的元数据、依赖包、脚本命令等信息。

初始化项目：在项目文件夹下运行npm init，它会以交互式问答的方式帮你创建package.json。如果嫌麻烦，可以加-y参数快速生成默认配置：npm init -y。

package.json关键字段解析：

• name: 项目名称。
• version: 项目版本，遵循语义化版本规则（主版本.次版本.修订号）。
• scripts: 定义一些可以通过npm run <script-name>执行的命令。例如，定义"start": "node app.js"，之后就可以用npm start来启动项目。
• dependencies:生产依赖。项目运行时必须的包，比如express,lodash。通过npm install <package-name> --save或npm install <package-name>安装的包会记录在这里。
• devDependencies:开发依赖。仅在开发阶段需要的包，比如测试框架jest、构建工具webpack。通过npm install <package-name> --save-dev安装。

npm常用命令：

• npm install <package-name>: 安装包到当前项目的node_modules文件夹，并写入dependencies。
• npm install <package-name>@<version>: 安装指定版本的包。
• npm install -g <package-name>: 全局安装包（通常用于命令行工具，如nodemon）。
• npm update <package-name>: 更新某个包。
• npm uninstall <package-name>: 卸载包。
• npm list: 查看当前项目安装的包及其依赖树。
• npm audit: 检查项目依赖中的安全漏洞。

实操心得：永远不要把node_modules文件夹提交到Git仓库！因为它体积巨大，且可以通过package.json和package-lock.json完美复现。确保你的.gitignore文件里包含了node_modules/。package-lock.json这个文件非常重要，它锁定了所有依赖包的确切版本，保证了团队不同成员或在不同环境安装时，得到完全一致的依赖树。请务必将它提交到仓库。

4. 核心API实战：从文件操作到HTTP服务器

理解了核心概念，我们开始动手写代码。Node.js的强大，在于它提供了一系列直接调用系统能力的API。我们从最常用的文件操作和创建Web服务器开始。

4.1 文件系统（fs模块）：与磁盘对话

fs模块提供了操作文件和目录的能力。它几乎所有函数都同时提供了同步和异步（回调风格和Promise风格）三种版本。

异步回调风格：这是最传统的方式，函数最后一个参数是回调函数，其第一个参数是错误对象err（Node.js约定俗成的“错误优先”风格）。

const fs = require('fs'); // 读取文件 fs.readFile('./example.txt', 'utf8', (err, data) => { if (err) { console.error('读取文件出错:', err); return; } console.log('文件内容:', data); }); // 写入文件 fs.writeFile('./output.txt', 'Hello Node.js!', 'utf8', (err) => { if (err) { console.error('写入文件出错:', err); return; } console.log('文件写入成功！'); });

同步风格：函数名以Sync结尾，会阻塞后续代码执行，直到操作完成。通常只在程序启动初始化等少数场景使用。

try { const data = fs.readFileSync('./example.txt', 'utf8'); console.log(data); } catch (err) { console.error(err); }

Promise风格 (fs/promises)：Node.js后期版本提供了基于Promise的API，可以用async/await语法，让异步代码看起来像同步一样清晰。

const fs = require('fs').promises; // 或者从 v14.8.0+ 可用 `const fs = require('fs/promises')` async function fileOps() { try { const data = await fs.readFile('./example.txt', 'utf8'); console.log(data); await fs.writeFile('./output.txt', data + '\nAppended!'); console.log('写入成功'); } catch (err) { console.error('操作失败:', err); } } fileOps();

个人建议：在新项目中，优先使用Promise风格 (fs.promises) 配合async/await，代码结构更清晰，避免了“回调地狱”。

其他常用操作：

• fs.existsSync(path): 同步检查文件/目录是否存在。
• fs.mkdir/fs.mkdirSync: 创建目录。
• fs.readdir: 读取目录内容。
• fs.stat/fs.statSync: 获取文件/目录状态信息（如大小、创建时间）。
• fs.rename: 重命名或移动文件/目录。
• fs.unlink: 删除文件。

4.2 HTTP模块：创建你的第一个Web服务器

这是Node.js最经典的用途。无需任何第三方框架，用核心的http模块就能创建一个Web服务器。

const http = require('http'); // 创建服务器实例 const server = http.createServer((req, res) => { // req (IncomingMessage): 包含请求信息，如URL、方法、请求头 // res (ServerResponse): 用于构建和发送响应 console.log(`收到请求: ${req.method} ${req.url}`); // 1. 设置响应头 res.setHeader('Content-Type', 'text/html; charset=utf-8'); // 2. 根据请求URL返回不同内容 if (req.url === '/') { res.statusCode = 200; // 状态码 200 OK res.end('<h1>欢迎来到Node.js服务器首页！</h1>'); } else if (req.url === '/about') { res.statusCode = 200; res.end('<h1>关于我们</h1><p>这是一个用原生Node.js创建的服务器。</p>'); } else { res.statusCode = 404; // 状态码 404 Not Found res.end('<h1>404 - 页面未找到</h1>'); } }); // 启动服务器，监听3000端口 const PORT = 3000; server.listen(PORT, () => { console.log(`服务器运行在 http://localhost:${PORT}`); });

保存为server.js，然后在终端运行node server.js。打开浏览器访问http://localhost:3000和http://localhost:3000/about，你就能看到不同的页面内容了。

代码解析：

1. http.createServer()接收一个请求监听器函数，每次有HTTP请求进来，这个函数就会被调用。
2. 函数接收两个对象：req（请求对象）和res（响应对象）。
3. 我们通过req.url和req.method来判断用户请求的是什么。
4. 通过res.setHeader()设置响应头（告诉浏览器返回的内容类型）。
5. 通过res.statusCode设置HTTP状态码。
6. 最后用res.end()发送响应体并结束本次请求响应周期。
7. server.listen()启动服务器，绑定到指定的端口和主机。

这个例子虽然简单，但它揭示了Web服务器最本质的工作流程：监听端口 -> 接收请求 -> 解析请求 -> 生成响应 -> 发送响应。所有复杂的Web框架（如Express、Koa）都是在这个基础上进行封装和扩展的。

4.3 路径处理（path模块）与流（Stream）

path模块：处理文件路径的利器。不同操作系统路径分隔符不同（Windows是\，Linux/macOS是/），直接用字符串拼接路径容易出错。path模块帮你解决这个问题。

const path = require('path'); const filePath = '/user/docs/letter.txt'; console.log(path.dirname(filePath)); // '/user/docs' 目录名 console.log(path.basename(filePath)); // 'letter.txt' 文件名 console.log(path.extname(filePath)); // '.txt' 扩展名 console.log(path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')); // '/foo/bar/baz/asdf' 智能拼接 console.log(path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')); // 解析为绝对路径

流（Stream）：处理大文件或连续数据的核心概念。想象一下，你要把一个大水箱的水搬到另一个地方，有两种方法：1. 拿桶把水全部舀出来，倒进另一个水箱（对应readFile全部读入内存）。2. 接一根水管，让水一边流入一边流出（对应流）。显然，第二种方法（流）更高效，不占用大量内存。 Node.js的流有四种类型：可读流（Readable）、可写流（Writable）、双工流（Duplex）、转换流（Transform）。文件读写、HTTP请求/响应、process.stdin/stdout都是流。

const fs = require('fs'); // 用流的方式复制大文件 const readStream = fs.createReadStream('./largefile.zip'); const writeStream = fs.createWriteStream('./largefile_copy.zip'); readStream.pipe(writeStream); // pipe（管道）将可读流的数据自动导向可写流 writeStream.on('finish', () => { console.log('文件复制完成！'); });

pipe方法自动处理了数据流动和背压（防止写入速度跟不上读取速度导致内存溢出），是处理流的推荐方式。

5. 异步编程进阶：从回调地狱到优雅异步

Node.js的异步特性是其优势，但也带来了著名的“回调地狱”问题。代码层层嵌套，难以阅读和维护。我们来看看解决方案的演进。

5.1 回调函数与“回调地狱”

最初的Node.js API大量使用回调函数。

fs.readFile('a.txt', 'utf8', (err, dataA) => { if (err) throw err; fs.readFile('b.txt', 'utf8', (err, dataB) => { if (err) throw err; fs.writeFile('c.txt', dataA + dataB, 'utf8', (err) => { if (err) throw err; console.log('文件合并完成！'); // 如果再需要更多操作，嵌套会更深... }); }); });

这种金字塔形状的代码就是“回调地狱”（Callback Hell）。它让错误处理变得复杂，流程控制困难。

5.2 Promise：异步编程的第一次革命

Promise对象代表一个异步操作的最终完成（或失败）及其结果值。它可以将嵌套的回调，转变为链式调用。

const fs = require('fs').promises; function readFilePromise(path) { // 实际上 fs.promises.readFile 已经返回Promise了，这里仅为演示 return fs.readFile(path, 'utf8'); } readFilePromise('a.txt') .then((dataA) => { return readFilePromise('b.txt').then((dataB) => dataA + dataB); }) .then((combinedData) => { return fs.writeFile('c.txt', combinedData, 'utf8'); }) .then(() => { console.log('文件合并完成！'); }) .catch((err) => { // 用一个catch捕获链中任何错误 console.error('操作失败:', err); });

代码结构变得扁平了一些，但.then链仍然不够直观，尤其是在需要用到前面结果的时候。

5.3 Async/Await：终极优雅方案

async/await是建立在Promise之上的语法糖，它让你能用写同步代码的方式写异步代码。

const fs = require('fs').promises; async function mergeFiles() { try { const dataA = await fs.readFile('a.txt', 'utf8'); const dataB = await fs.readFile('b.txt', 'utf8'); await fs.writeFile('c.txt', dataA + dataB, 'utf8'); console.log('文件合并完成！'); } catch (err) { console.error('操作失败:', err); } } mergeFiles();

代码逻辑一目了然，和同步代码几乎一样。async关键字用于声明一个函数是异步的，await关键字用于等待一个Promise完成并返回其结果。try...catch可以像处理同步错误一样处理异步错误。

重要注意事项：

1. await只能在async函数内部使用。
2. 调用一个async函数会立即返回一个Promise。如果你在顶层作用域（非async函数内）想使用await，在Node.js的ESM模块中可以直接用，在CommonJS中则需要用IIFE包裹：(async () => { await ... })();。
3. 不要滥用await！如果多个异步操作之间没有依赖关系，应该让它们并发执行，而不是串行等待，否则会丧失性能优势。

// 错误：串行，总耗时 = timeA + timeB const resultA = await fetchDataA(); const resultB = await fetchDataB(); // 正确：并行，总耗时 ≈ max(timeA, timeB) const promiseA = fetchDataA(); const promiseB = fetchDataB(); const [resultA, resultB] = await Promise.all([promiseA, promiseB]);

Promise.all接收一个Promise数组，当所有Promise都成功完成时，返回一个结果数组。如果其中任何一个被拒绝，整个Promise.all会立即被拒绝。

6. 常用工具与开发调试技巧

工欲善其事，必先利其器。掌握一些核心工具和调试技巧，能极大提升Node.js的开发效率。

6.1 Nodemon：开发时的自动重启神器

在开发阶段，每次修改代码后都需要手动停止 (Ctrl+C) 再重启 (node app.js) 服务器，非常繁琐。nodemon可以监视文件变化，自动重启Node.js应用。

1. 安装：npm install -g nodemon（全局安装，方便所有项目使用）或npm install --save-dev nodemon（作为项目开发依赖安装）。
2. 使用：将启动命令node app.js替换为nodemon app.js。
3. 高级配置：可以在项目根目录创建nodemon.json文件来配置监视的扩展名、忽略的目录等。

{ "watch": ["src/", "config/"], "ext": "js,json", "ignore": ["node_modules/", "dist/"], "exec": "node ./src/app.js" }

现在，当你保存代码文件时，nodemon会自动重启应用，浏览器刷新就能看到最新效果。

6.2 调试：从console.log到内置调试器

console.log大法：最简单直接，但效率低，需要反复添加和删除日志语句。

内置调试器与Chrome DevTools：Node.js内置了强大的调试器，并支持通过Chrome浏览器进行可视化调试。

1. 在启动命令中加入inspect标志：node --inspect app.js。你会看到类似Debugger listening on ws://127.0.0.1:9229/...的输出。
2. 打开Chrome浏览器，在地址栏输入chrome://inspect。
3. 在“Remote Target”区域，你应该能看到你的Node.js应用，点击下方的“inspect”链接。
4. 这会打开一个熟悉的Chrome开发者工具窗口，但它是连接到你的Node.js进程的！你可以在这里设置断点、单步执行、查看变量、调用栈，就像调试前端JavaScript一样。

VS Code集成调试：如果你用VS Code，调试体验更佳。

1. 点击左侧活动栏的“运行和调试”图标（或按Ctrl+Shift+D）。
2. 点击“创建一个 launch.json 文件”，选择“Node.js”。
3. 这会生成一个.vscode/launch.json配置文件。通常默认配置即可。
4. 在你的代码中点击行号左侧设置断点（红点）。
5. 按F5启动调试，程序会在断点处暂停，你可以使用调试工具栏（继续、单步跳过、单步进入等）进行调试，并在侧边栏查看变量和调用栈。

6.3 环境变量与配置管理

应用在不同环境（开发、测试、生产）通常需要不同的配置，比如数据库连接字符串、API密钥等。硬编码在代码中是极不安全的做法。正确的做法是使用环境变量。 Node.js通过process.env对象访问环境变量。

使用dotenv管理环境变量：

1. 安装包：npm install dotenv
2. 在项目根目录创建.env文件（务必将其加入.gitignore）：

   NODE_ENV=development DB_HOST=localhost DB_USER=root DB_PASS=s3cr3t API_KEY=your_api_key_here

3. 在应用入口文件的最顶部加载配置：

   require('dotenv').config(); // CommonJS // 或 import 'dotenv/config'; // ESM

4. 在代码中通过process.env使用：

   const dbConfig = { host: process.env.DB_HOST, user: process.env.DB_USER, password: process.env.DB_PASS }; const isProduction = process.env.NODE_ENV === 'production';

在生产环境中，你不需要.env文件，而是直接在服务器的系统环境变量中设置这些值（例如，在Linux中使用export命令，或在Docker、云平台的控制台设置）。

7. 实战：构建一个简单的静态文件服务器

让我们综合运用以上知识，构建一个比原生http模块例子更实用一点的工具：一个简单的静态文件服务器。它可以读取指定目录下的HTML、CSS、JS、图片等文件，并返回给浏览器。

const http = require('http'); const fs = require('fs').promises; const path = require('path'); const url = require('url'); // 定义静态资源目录 const PUBLIC_DIR = path.join(__dirname, 'public'); // 定义MIME类型映射 const MIME_TYPES = { '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml', '.ico': 'image/x-icon' }; const server = http.createServer(async (req, res) => { // 解析请求的URL，获取路径名 const parsedUrl = url.parse(req.url); let pathname = decodeURIComponent(parsedUrl.pathname); // 解码URL编码 // 默认首页 if (pathname.endsWith('/')) { pathname += 'index.html'; } // 构建实际文件路径 const filePath = path.join(PUBLIC_DIR, pathname); console.log(`请求文件: ${filePath}`); try { // 1. 检查文件是否存在且可访问 await fs.access(filePath); // 2. 读取文件状态，判断是否是目录（如果是，则找其下的index.html） const stats = await fs.stat(filePath); if (stats.isDirectory()) { // 重定向到目录下的index.html，或者列出目录（这里简单处理为404） res.statusCode = 404; res.end('Directory listing not supported.'); return; } // 3. 根据文件扩展名设置正确的Content-Type const ext = path.extname(filePath).toLowerCase(); const contentType = MIME_TYPES[ext] || 'application/octet-stream'; res.setHeader('Content-Type', contentType); // 4. 使用流读取文件并发送，避免大文件阻塞内存 const fileStream = fs.createReadStream(filePath); fileStream.pipe(res); // 处理流错误（如客户端中断连接） fileStream.on('error', (err) => { console.error('流读取错误:', err); if (!res.headersSent) { res.statusCode = 500; res.end('Internal Server Error'); } }); } catch (err) { // 文件不存在或无权限访问 console.error('文件错误:', err.code); res.statusCode = 404; res.setHeader('Content-Type', 'text/html; charset=utf-8'); res.end(`<h1>404 Not Found</h1><p>请求的资源 ${pathname} 不存在。</p>`); } }); const PORT = process.env.PORT || 3000; server.listen(PORT, () => { console.log(`静态文件服务器运行在 http://localhost:${PORT}`); console.log(`静态资源目录: ${PUBLIC_DIR}`); });

项目结构：

your-project/ ├── server.js └── public/ # 静态资源目录 ├── index.html ├── style.css └── image.jpg

运行与测试：

1. 创建上述目录和文件，在public/index.html里写点简单的HTML。
2. 运行node server.js。
3. 打开浏览器访问http://localhost:3000，你应该能看到index.html的内容。尝试访问http://localhost:3000/style.css或图片地址，它们也应该能被正确返回。

这个例子涵盖了路径安全处理、MIME类型设置、错误处理、流式响应等多个核心知识点，是一个非常好的综合练习。通过这个练习，你会对Node.js如何处理HTTP请求和响应有更深刻的理解。在此基础上，你可以尝试添加更多功能，比如缓存控制、Gzip压缩、目录浏览等，逐步把它完善成一个功能更全面的工具。