企业官网建设流程全解析

• 文档
• 教程
• 知识库

这篇 TIL 记录了 Netlify 平台上一个与构建工具链版本管理密切相关的关键细节：应用首次部署时，构建环境会把当时的默认 Yarn 版本"锁定"，此后所有构建与部署都沿用该版本；通过在其应用设置面板中配置YARN_VERSION环境变量（只需填写"主版本.次版本"），即可让下一次部署使用你指定的 Yarn 版本。读完本文，你将掌握YARN_VERSION的取值格式、配置入口、生效时机与验证方法，并理解 Netlify 构建环境"默认版本固化"的工作机制。

为什么 Netlify 会"锁定"默认 Yarn 版本

Netlify 的构建过程是在其云端构建镜像中完成的。该镜像预装了包括 Yarn 在内的一套工具链，当应用第一次部署到 Netlify 时，构建镜像中当时的默认 Yarn 版本会被记录下来并固定下来：

• 这个"锁定"的版本会用于后续所有的构建与部署；
• 它不会因为 Netlify 更新构建镜像而自动升级到新版本——默认版本在你首次部署那一刻就被固化了。

这也是原文出处（Netlify 社区论坛帖子）标题为Default Yarn version is now 1.17的原因：平台在某个时间点把默认 Yarn 版本调整到 1.17，之后首次部署的新站点便锁定这一版本。因此，如果你希望自己的站点使用与默认不同的 Yarn 版本，就需要显式覆盖它，而不是等待平台自动升级。

核心方案：使用YARN_VERSION环境变量覆盖默认版本

覆盖方式非常简单：在应用设置面板中配置YARN_VERSION环境变量。

两点需要特别留意：

1. 格式必须是 major.minor：文档明确指出取值为"desired major and minor version"，不要带上补丁号或完整版本字符串，例如写1.22即可。
2. 下一次部署生效：配置完成后不会立即影响当前已部署的版本，必须触发一次新的部署（重新部署当前分支、推送新提交，或从 Deploys 面板手动 Trigger deploy），新版本才会在构建时被使用。

YARN_VERSION与NODE_VERSION等变量同属 Netlify 构建环境中的"版本类"环境变量，它们让开发者无需修改代码或锁文件，即可控制构建工具链的版本。

逐步操作：在应用设置面板中覆盖 Yarn 版本

完整的操作路径如下：

1. 登录 Netlify，进入你的站点 Dashboard；
2. 打开**应用设置（Site settings / App settings）**面板，进入Build & deploy区域；
3. 找到Environment variables（环境变量）配置项；
4. 新增一个变量：
   • Key：YARN_VERSION
   • Value：例如1.22
5. 保存后触发一次新的部署，例如进入Deploys页面点击Trigger deploy → Deploy site；
6. 在本次部署的**构建日志（Build log）**中确认实际使用的 Yarn 版本符合预期。

可提交进仓库的替代方式：netlify.toml 声明环境变量

如果你希望把版本约束纳入版本控制、让团队所有成员的部署行为保持一致，也可以在仓库根目录的netlify.toml配置文件中声明构建环境变量：

[build] command = "yarn build" [build.environment] YARN_VERSION = "1.22"

• [build.environment]中声明的变量会在构建阶段注入，YARN_VERSION同样生效；
• 面板 / CLI 中设置的同名变量优先级更高，可以在不修改仓库的前提下临时覆盖netlify.toml中的值。

两种配置方式满足不同场景：面板配置适合快速调整、临时试验；netlify.toml适合长期固定、随代码评审共同演进。

如何确认新版本已经生效

配置YARN_VERSION并重新部署后，可以从两个层面验证：

1. 查看部署构建日志

在 Netlify 的 Deploys 页面进入最新一次部署，查看构建日志中依赖安装阶段输出的 Yarn 版本信息，确认与YARN_VERSION中填写的版本一致。

2. 本地对比版本

在本地项目目录中查看当前使用的 Yarn 版本，作为对照基准：

yarn --version

如果需要进一步核对依赖树中各个包的实际安装版本，可以参考仓库中另一篇 TIL Find The Version Of An Installed Dependency：使用yarn list --pattern <包名>查看指定依赖及其子依赖的版本树，或yarn list | fzf交互式筛选；而 Find Where Yarn Is Installing Binaries 则可以帮助定位yarn可执行文件的实际安装位置。

注意事项与边界

• 默认版本在首次部署时即被锁定：新站点第一次部署那一刻的默认 Yarn 版本会成为基线，之后不会再随构建镜像自动变化；
• 修改后必须重新部署：设置YARN_VERSION本身不会改变当前线上版本，触发新部署后才会生效；
• 取值为 major.minor：不要填入完整的三段版本号或构建号；
• 依赖安装方式与yarn.lock相关：Netlify 在检测到仓库中存在yarn.lock时，会采用 Yarn 来安装依赖，此时YARN_VERSION决定使用的 Yarn 版本；若仓库只有package-lock.json，则默认走 npm 流程；
• 环境变量属于站点级配置：YARN_VERSION作用于该站点的构建与部署，多个分支的构建共享这一配置。

原文位于仓库的 netlify/override-the-default-yarn-version.md，并收录于 README.md 的 Netlify 分类下。想进一步熟悉 Yarn 的日常使用，仓库中还有 Yarn Commands Without The Emojis 与 Pre And Post Hooks For Yarn Scripts 等笔记可供延伸阅读。

• 文档
• 教程
• 知识库