企业官网建设流程全解析

• 文档
• 教程
• 后端

本文围绕开源仓库 nodebestpractices 的日语版主文档 README.japanese.md 展开，系统梳理其中沉淀的8 大分类、共 101 项 Node.js 最佳实践，覆盖项目结构、错误处理、代码风格、测试与质量、生产环境、安全、性能与 Docker 容器化。读者读完本文，将掌握一套从「目录如何划分」到「线上如何监控、容器如何构建」的端到端可落地方案，并能在仓库各分节文档（sections/目录）中找到对应的深入讲解、代码示例与测试用例。

一、文档定位：这不是教程，而是一份「活」的最佳实践清单

在深入每一项实践之前，先理解这份文档的独特定位，这决定了你阅读和使用它的方式：

• 它是大量高质量内容的集大成者：README 开篇即说明，该仓库汇总了 Node.js 领域排名靠前的内容及协作作者（Collaborators）的原创产出，而不是某个作者的单一观点。
• 它持续更新：文档声明目前收录 80 多项（实际完整清单已达 101 项）最佳实践与架构提示，每天都有新的 Issue 和 Pull Request 在推进，属于「活的书」（living book），并欢迎代码修正、翻译与新增建议。
• 多数条目附带「进一步阅读」：每个条目下方的 🔗さらに読む链接指向sections/下的分节文档，包含代码示例、精选博客摘录与扩展信息。

文档正文按编号组织：1. 项目构成（5 项）、2. 错误处理（11 项）、3. 代码风格（12 项）、4. 测试与质量（13 项）、5. 生产环境（19 项）、6. 安全（25 项）、7. 性能（草稿阶段 2 项）、8. Docker（15 项）。下面我们逐板块解读，并在关键处结合仓库源码验证。

二、项目结构：用「组件 + 分层」对抗大项目熵增

2.1 按组件拆分，而不是按技术栈拆分

TL;DR：大型应用最糟糕的陷阱，是维护一个拥有成百上千依赖的巨型代码库——这样的单体会拖慢所有开发者的功能迭代速度。应将代码拆分为组件，每个组件拥有独立文件夹甚至独立代码库，并保证每个单元小而简单。

不这样做的话：新功能的开发者难以理解改动的影响面、害怕破坏其他依赖组件，部署变慢且风险变高；各业务单元没有隔离，扩展也会变得困难。进一步阅读见 breakintcomponents.japanese.md。

2.2 组件内部分层，Web 层不越界

每个组件应当包含专属的 Web、业务逻辑、数据访问对象（「层」）。这样不仅职责分离清晰，还让 mock 与测试大幅简化。常见反模式是 API 开发者把 Express 的req/res对象直接传给业务层和数据层——这会让应用与特定 Web 框架强耦合。后果是：混入 Web 对象的应用无法被测试代码、CRON 任务或消息队列触发器访问。详见 createlayers.japanese.md。

2.3 通用工具封装为（私有）npm 包

logger、加密等横切关注点，应封装进独立代码并作为私有 npm 包发布，便于跨代码库共享。否则每个项目都要重复造「部署与依赖的轮子」。详见 wraputilities.japanese.md。

2.4 把 Express 的 app 与 server 分离

不要把整个 Express 应用塞进一个巨型文件。至少拆成「API 声明」（app.js）与「网络相关」（www）两个文件，更好的做法是把 API 声明放进组件内部。否则 API 只能通过真实 HTTP 调用测试（生成覆盖率报告更慢、更难），且几百行代码挤在单文件里难以维护。详见 separateexpress.japanese.md。

2.5 分层且安全的配置

一份无懈可击的配置需要：(a) 键可从文件或环境变量读取；(b) 密钥不进入被提交的代码；(c) 配置分层、易于查找。文档推荐rc、nconf、config、convict等包。详见 configguide.japanese.md。

三、错误处理：从回调地狱到可控崩溃的 11 条军规

错误处理是 Node 应用稳定性的命门，本节 11 条实践层层递进。

3.1 用 Async-Await / Promise 取代回调

回调风格（function(err, response)）会导致正常逻辑与错误处理混为一谈、嵌套过深（Pyramid of doom），代码可维护性差。用 async-await 可获得 try-catch 般紧凑熟悉的语法。详见 asyncerrorhandling.japanese.md。

3.2 只用内置 Error 对象

无论 reject promise、抛异常还是 emit 错误，都应使用内置的Error对象（或其扩展），不要用字符串或自定义裸类型。否则调用方无法确定错误类型，且自定义类型会丢失stack等关键信息。详见 useonlythebuiltinerror.japanese.md。

3.3 区分「操作性错误」与「程序员错误」

• 操作性错误：如 API 收到非法输入，属于可预知、应被优雅处理的错误；
• 程序员错误：如引用未定义变量，属于未知代码缺陷，应立即重启进程。

若对每个可预期的小错误都重启应用，会让数千在线用户无谓掉线；反之，对未知错误放任进程继续运行也会导致不可预期的行为。详见 operationalvsprogrammererror.japanese.md。

3.4 集中化错误处理，中间件内不处理

管理邮件通知、日志等错误处理逻辑，应封装进一个专门的集中对象，由所有端点（Express 中间件、CRON、单元测试）统一调用。否则必然出现代码重复与「不恰当的处理」。详见 centralizedhandling.japanese.md。

3.5 用 Swagger / GraphQL 文档化 API 错误

REST 用 Swagger 这类文档框架，GraphQL 用 schema 与注释，让调用方知道会收到哪些错误、能优雅处理。否则客户端可能因未知错误直接崩溃重启（微服务场景下调用方往往就是你自己）。详见 documentingusingswagger.japanese.md。

3.6 未知事态发生时「体面地」终止进程

一旦出现未知错误（程序员错误），进程内部状态可能已不完整（例如全局 EventEmitter 内部出错不再触发事件），后续请求会连锁失败。此时应借助 Forever、PM2 等进程管理工具让进程退出并重启。详见 shuttingtheprocess.japanese.md。

3.7 用成熟日志库（Pino / Log4js）

console.log无法支撑规模化排障。Pino、Log4js 等成熟工具能加速错误的发现与理解。详见 usematurelogger.japanese.md。

3.8 用测试框架验证错误流

用 Mocha + Chai 等框架确保代码不仅满足正常路径，还能正确返回错误。否则「代码是否返回了正确错误」无从信任。详见 testingerrorflows.japanese.md。

3.9 用 APM 产品发现错误与停机

APM（应用性能监控）产品会主动探测代码库与 API，自动高亮被遗漏的错误、崩溃与慢路径。详见 apmproducts.japanese.md。

3.10 捕获未处理的 promise rejection

Promise 内抛出的异常若无人显式处理会被静默丢弃——即使订阅了process.uncaughtException也一样。必须监听process.unhandledRejection事件，否则错误被吞掉、连 trace 都不剩。详见 catchunhandledpromiserejection.japanese.md。

3.11 用专用库（ajv / Joi）做参数校验

手动写校验代码既繁琐又易漏。文档用一个典型 bug 说明：某函数期待数值参数Discount，调用方漏传导致Discount != 0的判断意外通过，用户白拿折扣。用ajv、Joi这类库可快速断言 API 输入。详见 failfast.japanese.md。

四、代码风格：让代码可读、可查、可维护

本节 12 条实践大多附有可直接复制的代码示例，这里完整继承。

4.1 ESLint + Prettier

ESLint 是代码潜在错误与风格检查的事实标准，既能揪出「不分类直接抛错」等反模式，也能自动修复风格问题；Prettier / beautify 与其配合做格式化。详见 eslint_prettier.japanese.md。

4.2 Node 专属 ESLint 插件

除 vanilla JS 标准规则外，还应加eslint-plugin-node、eslint-plugin-mocha、eslint-plugin-security。例如require(variableAsPath)这种让攻击者执行任意 JS 的模式，Node linter 能在早期就报警。

4.3 花括号与起始语句同行

// Do function someFunction() { // code block } // Avoid function someFunction() { // code block }

4.4 正确使用分号（注意 ASI 陷阱）

无论用不用分号，都要了解自动分号插入（ASI）的坑，避免意外语法错误；Prettier、Standardjs 可自动解决。

// する（推荐写法） function doThing() { // ... } doThing() const items = [1, 2, 3] items.forEach(console.log) // 避ける（会抛异常） const m = new Map() const a = [1,2,3] [...m.values()].forEach(console.log) // > SyntaxError: Unexpected token ... // 避ける（2() 被当作函数调用） const count = 2 (function doSomething() { // 凄いことをする }())

4.5 给函数命名

包括闭包与回调在内，所有函数都应命名。匿名函数会让内存快照（core dump）排查时无法判断内存被谁占用。本文档尤其建议 Node 应用做 profiling 时给函数命名。

4.6 命名规范：lowerCamelCase 与 UpperCamelCase

常量/变量/函数用lowerCamelCase，类用UpperCamelCase。因为 JS 是少数可以不new直接调用构造函数（「类」）的语言，靠首字母大写区分「需要实例化的类」与「普通函数」非常必要。

// クラスには、UpperCamelCase を使用します class SomeClassExample {} // const 名には const キーワードと lowerCamelCase を使用します const config = { key: "value", }; // 変数や関数名には lowerCamelCase を使用します let someVariableExample = "value"; function doSomething() {}

4.7 优先 const，其次 let，不要 var

const防止变量被重新赋值，让意图更清晰；需要重赋值时（如 for 循环）用let。let是块级作用域，而var是函数作用域，ES6 起已无使用必要。

4.8 在文件顶部 require 模块

require在 Node 中是同步执行的，若在函数内部调用，可能阻塞其他更关键请求的处理；模块加载失败也应尽早暴露而非隐藏在函数深处。

4.9 按文件夹 require，不直闯文件内部

在文件夹内放index.js作为对外「接口」，所有使用者都从它经过，未来改动内部文件签名不会破坏客户端。

// する module.exports.SMSProvider = require("./SMSProvider"); module.exports.SMSNumberResolver = require("./SMSNumberResolver"); // 避ける module.exports.SMSProvider = require("./SMSProvider/SMSProvider.js"); module.exports.SMSNumberResolver = require("./SMSNumberResolver/SMSNumberResolver.js");

4.10 使用===严格相等

==会先把两变量转成公共类型再比较，常常「非真即真」：

"" == "0"; // false 0 == ""; // true 0 == "0"; // true false == "false"; // false false == "0"; // true false == undefined; // false false == null; // false null == undefined; // true " \t\r\n " == 0; // true

换成===后，以上全部返回false。

4.11 用 Async-Await 替代回调

Node 8 LTS 已完整支持 async-await：非阻塞、让异步代码看起来像同步代码，配合 try-catch 语法最友好。回调风格会强制到处做错误检查、产生糟糕嵌套、让控制流难以推理。

4.12 使用箭头函数（=>）

处理接受 promise / callback 的老 API 时，箭头函数让结构更紧凑，并保留词法this。ES5 风格函数书写冗长且易出 bug。

五、测试与质量：把测试当作第一公民

5.1 至少先写 API（组件级）测试

项目常因工期紧跳过自动化测试，或让「测试项目」失控荒废。文档建议按优先级先从 API 测试入手——它最容易写、比单元测试覆盖更多（甚至可用 Postman 零代码手搓），再逐步补单元、DB、性能测试。

5.2 测试名包含三要素

测试名要表达「被测单元 + 场景 + 期望结果」。否则「Add product」失败时，没人知道到底哪里坏了。详见 3-parts-in-name.japanese.md。

5.3 用 AAA 模式组织测试

Arrange（准备）→ Act（执行）→ Assert（断言）三段式结构，让读者不必消耗脑力就能理解测试计划。详见 aaa.japanese.md。

5.4 用 Linter 提前发现问题

在测试之前运行 linter，并作为 pre-commit 的 git hook，能最小化 review 与修复成本。可结合上文「代码风格」板块。

5.5 避免全局测试夹具，每个测试自带数据

测试应使用各自的 DB 数据行，需要某条数据就显式插入，不要假定其他记录存在。否则会出现最经典的悲剧：系统其实是好的，只是测试互相干扰导致构建失败、团队浪费数小时排查。详见 avoid-global-test-fixture.japanese.md。

5.6 常查依赖漏洞

再知名的依赖（如 Express）也可能有已知漏洞。在 CI 中每次构建运行npm audit或 snyk.io 即可低成本检查。

5.7 给测试打标签

不同测试适配不同时机：无 I/O 的快速冒烟测试在开发者保存/提交时跑，完整 e2e 在 PR 提出时跑。用#cold#api#sanity等关键词标记，例如 Mocha 跑 sanity 组：mocha --grep 'sanity'。否则每次小改动都要跑包含大量 DB 查询的全量测试，慢到开发者干脆不跑了。

5.8 用覆盖率工具发现「错误」的测试

Istanbul / NYC 这类覆盖率工具免费且零成本受益：能发现覆盖率下滑，更能凸显测试错配——比如 catch 子句完全没被测试到，说明测试只走了 happy path。建议在覆盖率跌破阈值时让构建失败。

5.9 检查依赖过期

用npm outdated或npm-check-updates，把检查接入 CI，严重时（如落后 5 个 patch、被作者标记 deprecated）直接让构建失败、禁止部署该版本。

5.10 e2e 用贴近生产的环境

依赖 DB 等重服务的 e2e 测试是 CI 最薄弱环节，应尽量用接近生产的环境（原文档提示内容缺失，从其上下文推断应使用 docker-compose 实现环境一致性），避免各环境 DB 漂移导致结果不一致。

5.11 定期静态分析并重构

静态分析工具带来客观视角：能跨多文件查重、算代码复杂度、追踪问题历史。文档举例 SonarQube 与 Code Climate，配合 CI 可在发现 code smell 时失败构建。详见 refactoring.japanese.md。

5.12 慎重选 CI 平台

CI 托管所有质量工具，应选插件生态丰富的平台。Jenkins 社区最大但配置复杂、学习成本高；CircleCI 等 SaaS 省去基础设施管理，是「稳健性 vs 速度」的取舍。详见 citools.japanese.md。

5.13 隔离测试中间件

中间件若承载跨请求的大逻辑，值得脱离整个 Web 框架单独测试——只需 stub + spy 构造{req, res, next}对象即可。因为「Express 中间件里的 bug ≈ 所有请求的 bug」。详见 test-middlewares.japanese.md。

六、生产环境：从监控到部署的 19 项硬核操作

• 5.1 监控：监控是「抢在客户之前发现问题」的游戏，先定义必须守护的基础指标，再挑选覆盖全部需求的方案。详见 monitoring.japanese.md。
• 5.2 智能日志：从第一天就规划日志的收集、存储、分析，否则应用变成难以推理的黑盒。详见 smartlogging.japanese.md。
• 5.3 把 gzip / SSL 等交给反向代理：Node 不擅长 gzip、SSL 终止这类 CPU 密集任务，应交由 nginx、HAProxy 或云厂商中间件，避免单线程忙于基础设施任务拖垮应用性能。详见 delegatetoproxy.japanese.md。
• 5.4 锁定依赖：npm 默认会跨环境漂移（总是取最新 patch）。用.npmrc记录每个包的确切版本，或npm shrinkwrap做更细控制。NPM5 起依赖默认锁定，Yarn 也默认覆盖。详见 lockdependencies.japanese.md。
• 5.5 用合适工具守护进程存活：进程失败须重启。简单场景用 PM2；容器化世界还要考虑集群管理工具，避免「集群管理 + docker + PM2」叠床架屋造成 DevOps 混乱。详见 guardprocess.japanese.md。
• 5.6 用满所有 CPU 核：Node 默认只跑在单核上。中小应用用 Node cluster 或 PM2；大应用用 K8s/ECS 或 systemd 脚本复制进程。否则常见 4 核服务器只用了不到 25% 资源。详见 utilizecpu.japanese.md。
• 5.7 创建维护端点：用安全 API 暴露内存用量、REPL 等系统信息，避免为诊断临时「出诊断版代码」。详见 createmaintenanceendpoint.japanese.md。
• 5.8 APM 产品：APM 自动测量服务与层级间的用户体验，还能提示慢事务根因。详见 apmproducts.japanese.md。
• 5.9 面向生产写代码：从第一天就带着生产意识规划，否则再强的 DevOps 也救不了写得烂的系统。详见 productioncode.japanese.md。
• 5.10 测量并守护内存：v8 引擎对内存有约 1.4 GB 的软限制，Node 也有众所周知的泄漏路径。小应用可用 shell 命令定期测，中大应用应把内存监控接入正式监控系统。详见 measurememory.japanese.md。
• 5.11 前端静态资源移出 Node：用 nginx / S3 / CDN 提供前端内容，单线程 Node 流式输送数百个 html/images 会占用本应用于动态内容的所有资源。详见 frontendout.japanese.md。
• 5.12 保持无状态、经常「停服」：会话、缓存、上传文件等一律放外部存储；定期主动停服，或使用 AWS Lambda 这类 serverless 平台，避免单点故障与弹性扩展困难。详见 bestateless.japanese.md。
• 5.13 自动检测漏洞：用社区/商用工具在本地或 GitHub 上持续检查依赖漏洞。详见 detectvulnerabilities.japanese.md。
• 5.14 给每条日志分配事务 ID：transaction-id: {value}让同请求的日志可串联，排障时能还原「前后发生了什么」。Node 异步模型下实现不易，详见 assigntransactionid.japanese.md。
• 5.15 设置 NODE_ENV=production：许多 npm 包据此判断环境并优化生产代码。用 Express 做 SSR 时漏设NODE_ENV可能慢 3 倍。详见 setnodeenv.japanese.md。
• 5.16 设计自动化、原子化、零停机部署：研究显示部署越频繁的团队，严重生产事故概率越低。Docker + CI 是业界标准组合。
• 5.17 使用 Node.js LTS 版本：确保获得关键 bug 修复、安全更新与性能改进，否则新漏洞可能直接威胁生产应用。详见 LTSrelease.japanese.md。
• 5.18 不要在应用内做日志路由：日志目的地不应硬编码在代码里。开发者用 logger 写stdout，由运行环境（容器/服务器）把 stdout 流管道到 Splunk、Graylog、ElasticSearch 等。否则扩展难、易丢日志、职责分离差。详见 logrouting.japanese.md。
• 5.19 用npm ci安装：确保生产代码与测试时完全同版本。npm ci严格按 package.json 与 package-lock.json 做干净安装，适合 CI 等自动化环境。详见 installpackageswithnpmci.japanese.md。

七、安全：覆盖 OWASP Top 10 的 25 条防线

安全板块共 25 项，文档为多数条目标注了对应的 OWASP 威胁类型。逐条要点如下：

安全各条目均有对应分节文档，例如 limitrequests.japanese.md、secretmanagement.japanese.md、ormodmusage.japanese.md、secureheaders.japanese.md、dependencysecurity.japanese.md、bcryptpasswords.japanese.md、escape-output.japanese.md、validation.japanese.md、expirejwt.japanese.md、login-rate-limit.japanese.md、non-root-user.japanese.md、requestpayloadsizelimit.japanese.md、avoideval.japanese.md、regex.japanese.md、safemoduleloading.japanese.md、sandbox.japanese.md、childprocesses.japanese.md、hideerrors.japanese.md、sessions.japanese.md、saferedirects.japanese.md、avoid_publishing_secrets.japanese.md。

八、性能（草稿）：守住单线程事件循环

第 7 节仍处草稿阶段（仓库有 block-loop.japanese.md 与 nativeoverutil.japanese.md 两份分节文档），目前两条：

• 7.1 不要阻塞事件循环：CPU 密集任务应卸载到专用线程/进程/其他技术栈。事件循环一旦被阻塞，即使 3000 个用户的数据已就绪也发不出去——单个慢请求能卡住整台服务器。
• 7.2 优先原生 JS 方法而非 lodash 等工具库：不必要的依赖与性能损失不划算；新 ES 标准配合新 V8，原生方法比工具库快约 50%。

九、Docker：15 条容器化实践（附仓库源码级验证）

Docker 板块篇幅最长且几乎每条都有可运行示例，这里重点展开，并对照仓库真实 Dockerfile 验证。

9.1 多阶段构建：更瘦、更安全的镜像

核心思想：只把生产需要的制品拷贝到最终镜像，构建期工具（如 TypeScript CLI）用完即弃；构建期暴露的密钥也不进入运行期。

README 给出的最小示例：

FROM node:14.4.0 AS build COPY . . RUN npm ci && npm run build FROM node:slim-14.4.0 USER node EXPOSE 8080 COPY --from=build /home/node/app/dist /home/node/app/package.json /home/node/app/package-lock.json ./ RUN npm ci --production CMD [ "node", "dist/app.js" ]

仓库 multi_stage_builds.md 进一步给出了带.dockerignore（过滤node_modules、docs）、以 yarn 为例（yarn install --frozen-lockfile等价于 npm 的npm ci）以及「构建用完整镜像、运行用 alpine 最小镜像」的完整 Dockerfile。而仓库实际示例 Dockerfile 是可直接落地的参考实现，其关键结构：

• 构建阶段FROM node:14.8.0-alpine AS build，先apk add系统编译依赖，再只拷贝package.json+package-lock.json执行npm ci（保证可复现），拷贝源码后npm run build；
• 运行阶段FROM node:14.8.0-alpine as app，USER node非 root、EXPOSE 3000、WORKDIR /home/node/app；
• 从构建阶段拷贝dist与依赖，随后RUN npm prune --production && npm cache clean --force清理开发依赖与缓存；
• 启动用CMD [ "node", "dist/app.js" ]，而非npm start。

配套的 package.json 展示了build脚本（tsc --outDir dist -m commonjs -t ES2020 src/app.ts）以及 dependencies / devDependencies 的拆分——这正是「生产镜像只保留运行时依赖」的前提。

9.2 用 node 命令启动，避开 npm start

容器启动应写CMD ['node','server.js']。npm 脚本是中间进程，不会把 OS 信号透传给代码，导致应用得不到 SIGTERM 通知、丢失优雅关闭时机与进行中的请求/数据。分节文档见 bootstrap-using-node.japanese.md。

9.3 把复制与重启交给 Docker 运行时

在 Kubernetes 等编排环境里直接调用 Node 进程，不要再用 PM2、Cluster 模块做进程复制。运行时平台掌握的数据与可见性最多，最清楚该跑几个进程、如何分布、崩溃后怎么办；否则资源不足反复崩溃的容器会被进程管理器无限重启，而 K8s 本可把它挪到更宽裕的实例。详见 restart-and-replicate-processes.japanese.md。

9.4 .dockerignore 防密钥泄漏

.dockerignore过滤.env、.aws、.npmrc等个人密钥文件，否则会随镜像共享给所有能访问镜像仓库的人；顺带大幅缩短构建时间。详见 docker-ignore.japanese.md。

9.5 生产前清理依赖

最终镜像应剔除 devDependencies。多阶段构建中先装全部依赖，最后npm ci --production只留生产依赖，减小攻击面。历史上多起 npm 安全事故（如 eslint-scope 事件）就出在开发包上。详见 install-for-production.japanese.md。

9.6 聪明地优雅关闭

处理SIGTERM，在回应进行中请求的同时清理连接与资源。容器化运行时（尤其 K8s）里容器生灭是常态而非异常。分节文档 graceful-shutdown.japanese.md 明确给出了关闭阶段的流程图：

9.7 Docker 与 v8 双重内存限制

既要设 Docker 内存限制（供编排做明智的调度决策、避免饿死邻居），也要设--max-old-spacev8 标志让 GC 及时启动。实践经验：把 v8 old space 设为略小于容器限制值；只设 Docker 限制而不设 v8 限制，进程会在用到宿主约 50–60% 资源时崩溃。详见 memory-limit.japanese.md。

9.8 规划高效缓存

把「不常变化」的步骤放在 Dockerfile 上方（如依赖安装），「频繁变化」的（应用代码）放下方，利用层缓存实现近乎秒级重建。README 中该条链接指向的 use-cache 分节文档在当前仓库以 clean-cache.japanese.md 等文件承载相关缓存主题。

9.9 拒绝latest标签，用显式引用

latest并不能保证拿到「最新镜像」。用显式版本标签，更严格时用 SHA256 digest 引用，保证集群内所有实例跑完全相同的代码，避免基础镜像新版本带破坏性变更悄悄上线。详见 image-tags.japanese.md。

9.10 优先小基础镜像

大镜像意味着更大攻击面与更多资源消耗，优先 slim / Alpine。详见 smaller_base_images.japanese.md。

9.11 清理构建期密钥

npm token 等若作为 ARG 传入会残留在镜像层中，等于把私有 npm 仓库长期开放给攻击者。对策：多阶段构建 + 复制进.npmrc后删除（同时清构建历史），或使用不留痕迹的 BuildKit secret 功能。

9.12 扫描镜像多层漏洞

代码依赖干净不代表 OS 二进制（OpenSSL、TarBall 等）干净。部署前对最终镜像做 E2E 扫描（含 CI/CD 插件的免费/商用扫描器）。详见 scan-images.japanese.md。

9.13 清理 NODE_MODULE 缓存

装完依赖删除本地缓存——镜像不可变，缓存没有存在的意义；一行命令可省下通常占镜像体积 10–50% 的数十 MB。详见 clean-cache.japanese.md。

9.14 通用 Docker 建议集

与 Node 无直接关系的通用 Docker 实践汇总。详见 generic-tips.japanese.md。

9.15 Lint Dockerfile

用 Docker 专用 linter 检查偏离最佳实践的 Dockerfile，避免误把 root 当生产用户、使用不明来源镜像等低级但致命的问题。详见 lint-dockerfile.japanese.md。

十、如何把这 101 条实践用起来

1. 按板块对照自审：把本文 8 大板块当作 checklist，逐条对照你的项目，优先落地错误处理（第二节）、安全（第七节）与生产环境（第六节）中「不落地就会出事」的条目。
2. 深入分节文档：每个条目下的 🔗 链接指向sections/下的专属文档，含代码示例、反例与扩展阅读；本文所有分节链接均已转换为仓库根目录下的相对路径，可直接点入。
3. 参考仓库示例：构建 Docker 镜像时可直接对照 Dockerfile 与 package.json 的组合模式（多阶段、非 root、npm ci、npm prune --production、CMD ["node", ...]）。
4. 多语言版本对照：若需对照阅读，仓库提供 README.chinese.md、README.md 等十余种语言的翻译版本。
5. 参与共建：这是一个持续演进的「活」清单，仓库欢迎以提交 Issue / PR 的方式贡献修正、翻译与新思路，详见仓库根目录的贡献指南。

这份清单的价值不在于「背下来」，而在于把踩过坑的经验固化为可执行的工程纪律：结构上组件化分层、错误上区分可控与未知、质量上以测试和 CI 兜底、安全上对照 OWASP 逐条设防、容器上多阶段瘦身并优雅关闭。逐条落实，你的 Node.js 应用才能从「能跑」走向「能打」。

• 文档
• 教程
• 后端