Nixpacks 中的 Node.js 版本控制

Nixpacks 仅支持指定 Node.js 的主版本。本页将解释这一限制，并提供一种固定特定次要版本或补丁版本的工作区。

理解限制

根据 Nixpacks Node 提供程序文档：

"只能指定主版本。例如，18.x 或 20。"

当你通过以下方式指定 Node.js 版本时：

• NIXPACKS_NODE_VERSION 环境变量
• package.json 中的 engines.node
• .nvmrc 或 .node-version 文件

你只能控制主版本（例如，20、22）。具体的次要版本和补丁版本（例如，22.13.1 与 22.14.0）由 Nixpacks 内部使用的 nixpkgs 归档决定。

问题所在

你在 package.json 中设置了 "node": ">=22" 或 NIXPACKS_NODE_VERSION=22，但你的应用程序需要特定的 Node 22.14.0 版本。然而，Nixpacks 可能会提供 22.12.0 或其默认 nixpkgs 归档中的其他补丁版本——如果你的代码依赖于较新补丁版本中的功能，这会导致运行时问题。

解决方案

要固定特定的次要/补丁版本，你可以在 nixpacks.toml 文件中覆盖 nixpkgs 归档。在仓库根目录创建此文件：

[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'

nixpkgsArchive 的值是 NixOS/nixpkgs 仓库 中的提交 SHA。每个提交都包含特定的包版本，因此通过固定提交，你可以控制可用的确切版本。

查找正确的归档提交

要查找包含所需 Node.js 版本的 nixpkgs 提交：

1. 浏览 NixOS/nixpkgs 仓库
2. 搜索类似 v20.nix、v22.nix 或 v24.nix 的文件（Node.js 版本定义文件）
3. 检查添加所需版本的提交历史
4. 复制完整的提交 SHA

一些已验证的 Node.js 提交：

• 51ad838b03a05b1de6f9f2a0fffecee64a9788ee → Node 22.13.1
• bf744fe90419885eefced41b3e5ae442d732712d → Node 22.x 版本
• ffeebf0acf3ae8b29f8c7049cd911b9636efd7e7 → Node 22.14.0（不稳定分支）

在 Nixpacks 文档中了解更多关于 nixpkgs 归档 的信息。

Node.js 版本参考 (SHA256 哈希)

下表列出了 nixpkgs 历史中的 Node.js 版本及其 SHA256 哈希值。这些可以帮助你在处理 nixpkgs 归档时验证是否获得了预期的版本。