d73a73d7f3
- Replace fileURLToPath(import.meta.url) with import.meta.dirname across
scripts and extensions
- Rename parsers-legacy.ts → parsers.ts
- Remove deleted plan/spec docs (cicd-pipeline)
- Update package.json engines and deps across workspace packages
- Update web/package-lock.json
💘 Generated with Crush
Assisted-by: GLM-5.1 via Crush <crush@charm.land>
75 lines
2.1 KiB
Markdown
75 lines
2.1 KiB
Markdown
# 在 macOS 上通过 Homebrew 固定 Node.js LTS 版本
|
||
|
||
如果你是通过 Homebrew 安装 Node.js（`brew install node`），那你跟踪的是**当前最新正式版本**，其中可能包含奇数版本的开发分支（例如 23.x、25.x）。这些版本并不是 LTS，可能带来破坏性变更或稳定性问题。
|
||
|
||
SF 要求 Node.js **v24 或更高版本**，并且在 **LTS（偶数版本）** 上运行效果最好。本指南展示如何用 Homebrew 固定到 Node 24 LTS。
|
||
|
||
## 检查当前版本
|
||
|
||
```bash
|
||
node --version
|
||
```
|
||
|
||
如果输出的是奇数主版本号（例如 `v23.x`、`v25.x`），说明你当前使用的是开发版。
|
||
|
||
## 安装 Node 24 LTS
|
||
|
||
Homebrew 为 LTS 版本提供了带版本号的 formula：
|
||
|
||
```bash
|
||
# 取消当前版本（可能不是 LTS）的链接
|
||
brew unlink node
|
||
|
||
# 安装 Node 24 LTS
|
||
brew install node@24
|
||
|
||
# 将它设为默认版本
|
||
brew link --overwrite node@24
|
||
```
|
||
|
||
验证：
|
||
|
||
```bash
|
||
node --version
|
||
# 应显示 v24.x.x
|
||
```
|
||
|
||
## 为什么要固定到 LTS？
|
||
|
||
- **稳定性**：LTS 版本会在 30 个月内持续收到 bug 修复和安全更新
|
||
- **兼容性**：包括 SF 在内的 npm 包通常都会优先测试 LTS 版本
|
||
- **可预期**：`brew upgrade` 不会把你突然升级到不稳定的开发版
|
||
|
||
## 防止误升级
|
||
|
||
默认情况下，`brew upgrade` 会升级所有包，这可能让你离开固定版本。可以把对应 formula pin 住：
|
||
|
||
```bash
|
||
brew pin node@24
|
||
```
|
||
|
||
如果以后想取消固定：
|
||
|
||
```bash
|
||
brew unpin node@24
|
||
```
|
||
|
||
## 在多个版本之间切换
|
||
|
||
如果你需要同时使用多个 Node 版本（例如 22 和 24），更推荐使用版本管理器：
|
||
|
||
- **[nvm](https://github.com/nvm-sh/nvm)**：`nvm install 24 && nvm use 24`
|
||
- **[fnm](https://github.com/Schniz/fnm)**：`fnm install 24 && fnm use 24`（更快，基于 Rust）
|
||
- **[mise](https://mise.jdx.dev/)**：`mise use node@24`（多语言版本管理器）
|
||
|
||
这些工具允许你通过 `.node-version` 或 `.nvmrc` 为不同项目设置独立的 Node 版本。
|
||
|
||
## 验证 SF 是否正常工作
|
||
|
||
固定版本后，执行：
|
||
|
||
```bash
|
||
node --version # v24.x.x
|
||
npm install -g sf-run
|
||
sf --version
|
||
```
|