此页面记录了 Node.js 的构建系统，该系统负责在各种平台上配置、编译和打包 Node.js。它解释了构建架构、配置过程和跨平台构建机制。
有关运行测试的信息，请参阅测试和质量保证。
Node.js 构建系统基于多层架构，可将高级构建配置转换为特定于平台的构建指令。
来源：configure.py node.gyp Makefile vcbuild.bat tools/gyp_node.py
Node.js 的构建配置过程是构建管道的第一步。它将用户需求转换为机器可读的配置。
来源：configure.py vcbuild.bat node.gyp422-423
Node.js 构建系统中的关键配置文件包括：
| 文件 | 目的 |
|---|---|
node.gyp | 描述目标、源文件和依赖关系的主要构建定义文件 |
common.gypi | 通用构建变量和设置 |
config.gypi | 包含特定于平台和用户配置设置的生成文件 |
node.gypi | Node 特定的编译设置和选项 |
tools/v8_gypfiles/*.gypi | V8 特定构建配置 |
来源：node.gyp node.gypi tools/v8_gypfiles/features.gypi tools/v8_gypfiles/toolchain.gypi
配置过程会设置许多控制构建的变量
| 类别 | 示例 | 目的 |
|---|---|---|
| 架构 | target_arch, v8_target_arch | 指定目标 CPU 架构 |
| 模式 | debug, release | 影响优化和符号的构建类型 |
| 特性 | v8_enable_i18n_support, openssl_no_asm | 启用/禁用特定功能 |
| 依赖项 | node_shared_zlib, node_shared_openssl | 控制静态/动态链接 |
| 路径 | prefix, node_builtin_modules_path | 安装和模块路径 |
来源：configure.py42-60 configure.py91-139 node.gyp1-34
配置完成后，构建过程会将 Node.js 及其依赖项编译成可执行文件和库文件。
来源：Makefile107-136 node.gyp502-594 node.gyp822-997
Node.js 的主要构建目标包括：
| 目标 | 描述 | 可执行文件/位置 |
|---|---|---|
node_core_target_name | 主要的 Node.js 可执行文件 | out/Release/node |
node_lib_target_name | Node.js 核心库 | out/Release/libnode.a 或 out/Release/libnode.so |
v8_base_without_compiler | 核心 V8 引擎 | libnode 的一部分 |
mksnapshot | 创建 V8 快照的工具 | out/Release/mksnapshot |
cctest | C++ 单元测试框架 | out/Release/cctest |
来源：node.gyp517-736 node.gyp822-894 tools/v8_gypfiles/v8.gyp395-436
Node.js 可以在各种平台上进行构建，每个平台都有其特定的要求和过程。
对于包括 Linux 和 macOS 在内的类 Unix 系统，构建过程使用 configure.py 来生成配置，并使用 make 来执行构建。
来源：BUILDING.md267-278 Makefile267-308
在 Windows 上，构建过程使用 vcbuild.bat 通过 Visual Studio 构建工具进行配置和构建。
来源：BUILDING.md761-776 vcbuild.bat762-815
Node.js 拥有几个核心依赖项，这些依赖项在构建过程中进行管理。
来源： node.gyp17-27 configure.py266-553 BUILDING.md129-192
Node.js 提供选项，可使用捆绑的静态库或系统提供的共享库。
| 依赖项 | 静态选项 | 共享选项 | 配置变量 |
|---|---|---|---|
| OpenSSL | 捆绑 | 系统 | node_shared_openssl |
| zlib | 捆绑 | 系统 | node_shared_zlib |
| libuv | 捆绑 | 系统 | node_shared_libuv |
| http_parser | 捆绑 | 系统 | node_shared_http_parser |
| nghttp2 | 捆绑 | 系统 | node_shared_nghttp2 |
| ICU | 各种模式 | 系统 ICU | with_intl |
来源： configure.py259-554 node.gyp17-28
构建系统包含各种优化，以提高构建性能和二进制文件的大小/性能。
| 优化 | 标志 | 描述 |
|---|---|---|
| ccache | --use-ccache-win | 通过缓存中间输出来加速编译。 |
| 链接时优化 | --enable-lto | 在链接时启用跨模块优化。 |
| 基于配置文件的优化 | --enable-pgo-generate/--enable-pgo-use | 使用运行时配置文件数据来优化代码。 |
| Ninja | BUILD_WITH=ninja | 另一个更快的构建系统。 |
| 基于磁盘的 JS 文件 | --node-builtin-modules-path | 从磁盘加载 JS 文件，而不是嵌入。 |
来源： configure.py208-215 BUILDING.md544-592 Makefile140-149
构建后，Node.js 可以安装到系统中。
来源： tools/install.py91-116 tools/install.py152-205 Makefile190-193
常见的构建问题及解决方案
| 问题 | 可能解决方案 |
|---|---|
| 缺少依赖项 | 安装所需的开发包 |
| 编译器版本不匹配 | 使用推荐的编译器版本。 |
| OpenSSL ASM 故障 | 使用 --openssl-no-asm 进行构建。 |
| 文件未找到错误 | 尝试 make distclean 并重新构建。 |
| 内存错误 | 使用 -j2 减少并行任务数，或增加 RAM。 |
| Windows vcpkg 问题 | 运行 vcpkg integrate remove。 |
来源： BUILDING.md595-609 BUILDING.md626-631
Node.js 为特定用例提供了一些高级构建选项。
| 选项 | 描述 | 用例 |
|---|---|---|
--debug | 启用带符号的调试构建。 | 调试和开发 |
--fully-static | 创建完全静态的可执行文件。 | 容器化部署 |
--enable-vtune-profiling | 启用 Intel VTune 性能分析器支持。 | 性能分析 |
--coverage | 启用代码覆盖率。 | 测试覆盖率测量 |
--openssl-fips | 使用符合 FIPS 标准的 OpenSSL 构建。 | 安全合规性 |
--without-intl | 禁用国际化支持。 | 更小的二进制文件大小 |
来源： configure.py92-126 configure.py189-207 BUILDING.md489-502
Node.js 支持构建单一可执行应用程序 (SEA)。
Node.js 默认启用 SEA 支持，除非使用 --disable-single-executable-application 配置标志明确禁用。