Upcoming breaking changes for npm v12
Upcoming breaking changes for npm v12
npm v12 即将推出的重大变更
Back to changelog Our next npm major version, v12, introduces security-related default changes to npm install. All these changes are available behind warnings in npm today on 11.16.0 or newer, so you can prepare before the upgrade. v12 is estimated to release in July 2026.
回到更新日志。我们的下一个 npm 主版本 v12 将针对 npm install 引入与安全相关的默认设置变更。目前，所有这些变更已在 npm 11.16.0 及更高版本中通过警告提示提供，以便您在升级前做好准备。v12 预计将于 2026 年 7 月发布。
Each change turns an npm install behavior that runs automatically today into one you explicitly opt into:
每一项变更都将目前自动运行的 npm install 行为转变为需要您明确选择开启的行为：
allowScripts defaults to off: npm install will no longer execute preinstall, install, or postinstall scripts from dependencies unless they are explicitly allowed in your project. This includes native node-gyp builds (i.e., a package with a binding.gyp and no explicit install script still gets blocked, because npm runs an implicit node-gyp rebuild for it). prepare scripts from git, file, and link dependencies are blocked the same way. To see what would be blocked, run npm approve-scripts —allow-scripts-pending. Then allow the packages you trust with npm approve-scripts and block the rest with npm deny-scripts. The resulting allowlist is written to package.json and should be committed. If your install routine runs scripts, you can observe warnings in npm 11.16.0+.
allowScripts 默认关闭：除非在您的项目中明确允许，否则 npm install 将不再执行依赖项中的 preinstall、install 或 postinstall 脚本。这包括原生的 node-gyp 构建（即带有 binding.gyp 文件但没有显式安装脚本的包也会被拦截，因为 npm 会为其运行隐式的 node-gyp rebuild）。来自 git、file 和 link 依赖项的 prepare 脚本也会以同样方式被拦截。要查看哪些脚本会被拦截，请运行 npm approve-scripts --allow-scripts-pending。然后使用 npm approve-scripts 允许您信任的包，并使用 npm deny-scripts 拦截其余包。生成的白名单将写入 package.json 并应提交到版本控制中。如果您的安装流程运行了脚本，您可以在 npm 11.16.0+ 版本中观察到相关警告。
—allow-git defaults to none: npm install will no longer resolve Git dependencies (direct or transitive) unless explicitly allowed via —allow-git. This closes a code-execution path where a Git dependency’s .npmrc could override the Git executable, even with —ignore-scripts. This change was previously announced on 2026-02-18 and is available in npm 11.10.0+.
--allow-git 默认设为无：除非通过 --allow-git 明确允许，否则 npm install 将不再解析 Git 依赖项（直接或间接依赖）。这关闭了一个代码执行路径，即 Git 依赖项的 .npmrc 可能会覆盖 Git 可执行文件，即使使用了 --ignore-scripts 也是如此。此变更已于 2026 年 2 月 18 日宣布，并已在 npm 11.10.0+ 中提供。
—allow-remote defaults to none: npm install will no longer resolve dependencies from remote URLs, such as https tarballs (direct or transitive), unless explicitly allowed via —allow-remote. This flag is available in npm 11.15.0+. The related —allow-file and —allow-directory flags are not changing their defaults in v12.
--allow-remote 默认设为无：除非通过 --allow-remote 明确允许，否则 npm install 将不再解析来自远程 URL（如 https tarball）的依赖项（直接或间接依赖）。此标志在 npm 11.15.0+ 中可用。相关的 --allow-file 和 --allow-directory 标志在 v12 中不会更改其默认设置。
How to prepare: Upgrade to npm 11.16.0 or later, run your normal install, and review the warnings. Use npm approve-scripts —allow-scripts-pending to see which packages have scripts, approve the ones you trust, and commit the updated package.json. After that, only the scripts you approved keep running once you upgrade. Anything you leave unapproved will stop. More details are available in our docs at npm approve-scripts, npm deny-scripts, and allow-scripts config (for npx and global installs). Please share your comments and questions in our community discussion.
如何准备：升级到 npm 11.16.0 或更高版本，运行正常的安装流程，并查看警告信息。使用 npm approve-scripts --allow-scripts-pending 查看哪些包包含脚本，批准您信任的包，并提交更新后的 package.json。此后，一旦您升级，只有您批准的脚本才会继续运行。任何未被批准的脚本都将停止运行。更多详细信息请参阅我们的文档：npm approve-scripts、npm deny-scripts 以及 allow-scripts 配置（针对 npx 和全局安装）。请在我们的社区讨论中分享您的意见和问题。