Node.js Best Practices 是一份面向 2025 年的 Node.js 开发原则与决策指南，核心目标不是让人背诵固定的代码模式，而是学会根据具体情境进行判断与选择。资料明确指出，使用该技能时应向用户询问偏好（当需求不清晰时），基于上下文选择框架与模式，而不是每次都默认同一套解决方案。
一、框架选择（2025） 资料提供了一棵决策树：构建边缘/无服务器应用（Cloudflare、Vercel）时可考虑 Hono（零依赖、极快的冷启动）；高性能 API 可选 Fastify（据称比 Express 快 2-3 倍）；企业级或团队熟悉场景可用 NestJS（结构化、依赖注入、装饰器）；遗留、稳定或需要最大生态时用 Express（成熟、中间件最多）；全栈配合前端则可用 Next.js API Routes 或 tRPC。 对比原则中列出 Hono、Fastify、Express 在适用场景、冷启动（最快/快/中等）、生态（成长中/良好/最大）、TypeScript 支持（原生/优秀/良好）、学习曲线（低/中/低）上的差异。选择前应问：部署目标是什么？冷启动时间是否关键？团队是否有既有经验？是否有遗留代码需要维护？
二、运行时考量（2025） Node.js 22+ 支持 --experimental-strip-types，可直接运行 .ts 文件，简单项目无需构建步骤，适合脚本与简单 API。模块系统方面，ESM（import/export）是现代标准、具备更好的 tree-shaking 与异步模块加载，适合新项目；CommonJS（require）兼容遗留、更多 npm 包支持，适合既有代码库与部分边缘场景。运行时选择上，Node.js 适合通用与最大生态，Bun 侧重性能与内置打包器，Deno 强调安全优先与内置 TypeScript。
三、架构原则 分层结构建议请求流经控制器/路由层（处理 HTTP 细节、在边界做输入验证、调用服务层）、服务层（业务逻辑、框架无关、调用仓储层）、仓储层（仅数据访问、数据库查询、ORM 交互）。其价值在于可测试性（独立 mock 各层）、灵活性（换数据库不影响业务逻辑）、清晰性（每层单一职责）。小脚本可单文件，原型可减少结构，但应始终自问“它会成长吗？”
四、错误处理原则 采用集中式错误处理：创建自定义错误类、在任意层抛出、在顶层（中间件）捕获、格式化一致响应。返回给客户端的应包含合适的 HTTP 状态码、便于程序处理的错误码、用户友好消息，且不含内部细节（安全考虑）；日志中则记录完整堆栈、请求上下文、用户 ID（如适用）与时间戳。状态码包括 400 输入错误、401 未认证、403 无权限、404 未找到、409 冲突、422 校验失败、500 服务器错误。
五、异步模式原则 async/await 用于顺序异步操作，Promise.all 用于并行且相互独立的操作，Promise.allSettled 用于并行但允许部分失败，Promise.race 用于超时或首个响应获胜。I/O 密集任务（数据库查询、HTTP 请求、文件系统、网络）异步有效；CPU 密集任务（加密、图像处理、复杂计算）异步无效，应使用 worker threads 或卸载处理。应避免在生产环境使用同步方法，卸载 CPU 密集工作，用流处理大数据。
六、验证原则 在边界处验证：API 入口（请求体/参数）、数据库操作前、外部数据（API 响应、文件上传）、环境变量（启动时）。验证库可选 Zod（TypeScript 优先、可推断）、Valibot（更小体积、可 tree-shake）、ArkType（性能关键）、Yup（既有 React Form 使用）。理念是快速失败、尽早验证、错误信息明确，并且不信任任何数据，包括“内部”数据。
七、安全原则 清单包含：验证所有输入；参数化查询、SQL 不拼接字符串；密码哈希使用 bcrypt 或 argon2；JWT 始终验证签名与有效期；限流防滥用；安全头（Helmet.js 或等价方案）；生产环境全站 HTTPS；正确配置 CORS；密钥只放环境变量；定期审计依赖。心态上不信任查询参数、请求体、请求头、Cookie、文件上传与外部 API 响应。
八、测试原则 单元测试针对业务逻辑，工具可用 node:test、Vitest；集成测试针对 API 端点，用 Supertest；端到端测试覆盖完整流程，用 Playwright。优先测试关键路径（认证、支付、核心业务）、边界情况（空输入、边界值）、错误处理；框架代码与琐碎 getter 不值得测试。Node.js 22+ 可用内置测试运行器 node --test。
九、应避免的反模式 不要为新边缘项目使用 Express（应用 Hono）；不要在生产代码中使用同步方法；不要把业务逻辑放进控制器；不要跳过输入验证；不要硬编码密钥；不要未经验证就信任外部数据；不要用 CPU 工作阻塞事件循环。应当基于上下文选择框架、不清晰时询问用户偏好、成长型项目使用分层架构、验证所有输入、密钥用环境变量、优化前先做性能分析。
十、决策清单 实现前应确认：是否询问过用户技术栈偏好？是否为当前上下文选择了框架（而非默认）？是否考虑部署目标？是否规划错误处理策略？是否确定验证点？是否考虑安全需求？资料强调：Node.js 最佳实践的关键是决策，而非记忆模式，每个项目都应基于其需求重新考量。