1. 为什么 Windows 下 Node.js 版本管理总出问题
如果你在 Windows 上用 PowerShell 写代码，多半遇到过这种场景：公司老项目锁死 Node 12，新项目要 Node 22，全局装了一个版本，切来切去要么node -v不生效，要么重启终端又变回去。更麻烦的是 OpenCode 这类 CLI 工具，它启动时依赖特定 Node 版本，版本一乱就直接报错退出，你连日志都看不全。
我试过最原始的办法——手动去官网下 msi 包，装一个卸一个。结果 PATH 里残留一堆旧路径，where node能列出三四个结果，PowerShell 每次启动都要重新认一遍。后来改用 nvm-windows，虽然能切版本，但它对 PowerShell 的支持一直不太顺，nvm use之后当前窗口经常不刷新，还得手动改环境变量。
fnm（Fast Node Manager）是 Rust 写的，启动快、跨平台，最关键的是它对 PowerShell 的集成做得干净。配合fnm env --use-on-cd，你cd进任何带.node-version的目录，它自动帮你切好版本，退出再切回来。OpenCode 这种对 Node 版本敏感的 CLI，只要默认版本设对，基本不会再因为版本问题启动失败。
这篇就按「卸载旧 Node → winget 装 fnm → 配 PowerShell 初始化 → 装版本 → 验证 OpenCode」的顺序走一遍，命令都能直接复制。适合谁？就是那些在 Windows PowerShell 里管 Node、又被版本切换折磨过的开发者。下面每一步我都会说明「为什么这么做」和「不做会怎样」，你照着敲就行。
2. 前置准备：清理旧 Node 与安装 fnm 的完整流程
在装 fnm 之前，有一件事必须先做：把系统里已有的 Node.js 清干净。这不是多此一举，而是因为 Windows 的 PATH 查找顺序是从上到下的，如果你之前用 msi 装过 Node，它的路径会写在系统环境变量里，优先级往往高于 fnm 注入的路径。结果就是：你fnm use 22明明成功了，node -v还是显示旧版本。
先查一下当前装了哪些 Node 相关的东西。打开 PowerShell，跑这条：
Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -like "*Node*" } | Select-Object Name如果输出里有 Node.js 字样，去「设置 → 应用 → 已安装的应用」里手动卸载它。卸载完记得重启一次终端，让 PATH 刷新。有些同学会问：能不能不卸载，直接让 fnm 覆盖？实测下来不行，msi 装的 Node 会往C:\Program Files\nodejs写，这个路径在系统变量里，fnm 管不到它。
清理干净后，用 winget 装 fnm。winget 是 Windows 自带的包管理器，Win10 1809 以上、Win11 都有。命令就一行：
winget install Schniz.fnm装完先别急着用，因为 fnm 的可执行文件路径还没进当前会话的 PATH。关掉 PowerShell 重新开一个，然后验证：
fnm --version能打印出版本号（比如fnm 1.38.1）就说明装好了。如果提示「无法将 fnm 项识别为 cmdlet」，说明 PATH 没生效，检查一下%LOCALAPPDATA%\Microsoft\WinGet\Links是否在用户环境变量里。winget 装的东西默认会往这里放软链接。
接下来是可选但强烈建议的一步：自定义 fnm 的安装目录。fnm 默认把 Node 版本装到用户目录下（%APPDATA%\fnm附近），C 盘紧张的话可以改到 D 盘。先建目录：
New-Item -ItemType Directory -Path "D:\Programs\fnm" -Force然后把这个路径写进 PowerShell 配置文件。这里有个坑：$PROFILE变量指向的路径可能包含空格（比如My Document），直接Add-Content有时会出问题。稳妥做法是先确认路径存在：
$PROFILE_PATH = $PROFILE.CurrentUserAllHosts if (-not (Test-Path $PROFILE_PATH)) { New-Item -ItemType File -Path $PROFILE_PATH -Force }确认文件存在后，再往里追加配置。下面这几行是核心，我逐条解释：
Add-Content -Path $PROFILE_PATH -Value '$env:FNM_DIR = "D:\Programs\fnm"' Add-Content -Path $PROFILE_PATH -Value '$env:FNM_NODE_DIST_MIRROR = "https://npmmirror.com/mirrors/node"' Add-Content -Path $PROFILE_PATH -Value 'fnm env --use-on-cd | Out-String | Invoke-Expression'第一行把 fnm 的存储目录指到 D 盘。第二行设置 Node 下载镜像，国内直连 nodejs.org 经常超时，换成 npmmirror 会快很多。第三行是 fnm 的 shell 集成，--use-on-cd让它在切换目录时自动读.node-version并切版本，Out-String | Invoke-Expression是把 fnm 输出的环境变量脚本在当前会话里执行。
这里要特别提醒一个报错：如果你用的 fnm 版本较新，生成的补全脚本里可能带using namespace语句。PowerShell 要求using namespace必须出现在文件最顶部，否则加载 profile 时会报「Using namespace 语句必须位于脚本顶部」。解决办法是打开$PROFILE_PATH，把这两行手动挪到文件第一行：
using namespace System.Management.Automation using namespace System.Management.Automation.Language改完保存，重新加载配置：
. $PROFILE如果没报错，说明 fnm 的 shell 集成已经生效。这一步是整个流程的地基，后面 OpenCode 能不能正常跑，全看这里配得对不对。
3. 可复制配置：fnm 环境变量与 OpenCode 兼容设置
上一节把 fnm 装好、profile 配好了，这一节把配置固化下来，方便你以后换机器直接抄。fnm 在 PowerShell 里真正起作用，靠的是三块：环境变量、profile 初始化脚本、以及项目级的版本文件。我把它整理成一份可以直接复制的配置清单。
先说环境变量。fnm 认这几个变量，你按需设置：
| 变量名 | 作用 | 建议值 |
|---|---|---|
FNM_DIR | Node 版本安装目录 | D:\Programs\fnm |
FNM_NODE_DIST_MIRROR | Node 下载镜像 | https://npmmirror.com/mirrors/node |
FNM_DEFAULT | 默认版本（可选） | 22 |
FNM_LOGLEVEL | 日志级别 | info |
这些变量写进 PowerShell profile 就行。如果你想让它们对所有 shell 生效，也可以写进系统环境变量，但我不推荐——系统变量改起来麻烦，profile 更灵活。
然后是 profile 初始化脚本。完整的Microsoft.PowerShell_profile.ps1内容大概长这样，你可以直接对照：
# fnm 配置 $env:FNM_DIR = "D:\Programs\fnm" $env:FNM_NODE_DIST_MIRROR = "https://npmmirror.com/mirrors/node" # fnm shell 集成 fnm env --use-on-cd | Out-String | Invoke-Expression注意fnm env这行必须放在环境变量设置之后，因为它会读取FNM_DIR来决定把哪些路径注入 PATH。顺序反了，fnm 会用它默认的目录，你的自定义就白设了。
接下来是 OpenCode 的兼容配置。OpenCode 是个 CLI 工具，通过 npm 全局安装，它启动时会调用当前 PATH 里的node。所以只要 fnm 把默认版本设对，OpenCode 就能正常跑。安装命令：
npm i -g opencode但这里有个细节：如果你之前用旧 Node 装过 opencode，卸载旧 Node 后全局包会丢，需要重装。重装前先确认当前 Node 版本：
fnm current输出应该是你设的默认版本，比如v22.11.0。如果显示none或者旧版本，先执行：
fnm install 22 fnm default 22fnm install 22会从你配的镜像下载 Node 22，fnm default 22把它设为默认。之后新开的终端都会用这个版本。
如果你有项目需要特定 Node 版本，比如某个老前端项目锁 Node 12，就在项目根目录建一个.node-version文件：
echo "12" > .node-version然后cd进这个目录，fnm 会自动切到 Node 12。退出目录，自动切回默认版本。这个机制对 OpenCode 特别友好——你在不同项目间跳来跳去，不用手动fnm use，它自己就切好了。
还有一点关于 OpenCode 的配置。OpenCode 支持通过环境变量指定模型和 API 端点，如果你用的是 TaoToken 这类兼容 OpenAI 协议的服务，可以在 profile 里加：
$env:OPENCODE_API_KEY = "你的Key" $env:OPENCODE_BASE_URL = "https://taotoken.net/api"这样 OpenCode 启动时就会读这些变量，不用每次手动传参。Key 的获取在下一节说。
4. 验证请求：fnm 切版本后 OpenCode 正常启动
配置写完，必须验证。很多人配完 fnm 就直接开 OpenCode，结果报错又回头查，效率很低。这一节给你一套可复制的验证步骤，从 fnm 本身到 OpenCode 启动，逐层确认。
第一步，验证 fnm 能正常切版本。开一个新的 PowerShell 窗口（重要，必须是新窗口，这样才会加载最新 profile），执行：
fnm list如果输出是空的，说明还没装任何版本。先装：
fnm install 22 fnm install 12再fnm list，应该能看到两个版本，当前使用的那个前面有个星号。然后测试切换：
fnm use 12 node -vnode -v应该输出v12.x.x。再切回来：
fnm use 22 node -v输出v22.x.x。这一步过了，说明 fnm 的核心功能没问题。
第二步，验证.node-version自动切换。建个测试目录：
mkdir D:\test-node12 cd D:\test-node12 echo "12" > .node-version node -v如果输出v12.x.x，说明--use-on-cd生效了。cd出去再node -v，应该回到 22。这一步是 OpenCode 兼容的关键——OpenCode 在不同项目里跑，靠的就是这个自动切换。
第三步，验证 OpenCode 能启动。先确认全局包在：
npm list -g --depth=0输出里应该有opencode。如果没有，重装：
npm i -g opencode然后直接跑：
opencode --version能打印版本号就说明 OpenCode 在当前 Node 下能正常加载。如果报错Cannot find module或者SyntaxError，多半是 Node 版本不对——OpenCode 较新版本要求 Node 18+，你如果当前是 12 就会挂。用fnm current确认，不对就fnm use 22。
第四步，验证 OpenCode 能实际发请求。这一步需要 API Key。如果你还没 Key，去 TaoToken 控制台创建一个：
# 打开浏览器到 API Keys 页面 start https://taotoken.net/console/api-keys创建后复制 Key，设到环境变量：
$env:OPENCODE_API_KEY = "sk-你的Key"然后跑一个最简单的对话测试：
opencode "用一句话解释什么是 Node.js"如果 OpenCode 正常返回一段文字，说明从 fnm 到 Node 到 OpenCode 到 API 的整条链路都通了。这一步成功的结果是：终端里打印出模型返回的解释，没有报错，没有卡住。
如果卡住或者报401，检查 Key 是否复制完整、有没有多余空格。报local proxy failed的话，检查OPENCODE_BASE_URL是不是写成了https://taotoken.net/api（注意结尾没有斜杠）。报reading choices一般是返回体格式不对，确认你用的模型 ID 在 TaoToken 的模型列表里存在。
5. 本篇常见错排查：401、local proxy failed 与 OAuth 报错
配置过程中最容易卡住的就那几个报错，我把它们和真实场景对照着列出来，你遇到直接对号入座。
报错一：fnm : 无法将“fnm”项识别为 cmdlet
这是 PATH 没生效。winget 装完 fnm 后，软链接在%LOCALAPPDATA%\Microsoft\WinGet\Links，这个路径需要在新终端里才会进 PATH。解决办法：关掉所有 PowerShell 窗口，重新开一个。如果还不行，手动检查用户环境变量：
$env:Path -split ';' | Select-String "WinGet"没有输出的话，手动加：
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\Microsoft\WinGet\Links", "User")然后重开终端。
报错二：fnm use成功但node -v不变
这是旧 Node 的 PATH 优先级更高。回到第 2 节，用Get-WmiObject查一下有没有残留的 Node 安装，有就卸载。卸载后重启终端。还有一种可能是 profile 里fnm env那行没执行，检查. $PROFILE有没有报错。
报错三：401 Unauthorized
OpenCode 请求 TaoToken 时返回 401，说明 Key 不对。检查三件事：Key 有没有复制完整（有时候复制会漏掉最后几位）、有没有多余空格、Key 是不是已经过期或被删。重新去控制台生成一个，设到环境变量：
$env:OPENCODE_API_KEY = "sk-新Key"注意环境变量只在当前会话有效，新开终端要重新设，或者写进 profile。
报错四：local proxy failed或连接超时
这个报错通常是 Base URL 写错了。OpenCode 连 TaoToken 的地址是https://taotoken.net/api，注意结尾没有斜杠，也没有/v1。如果你写成了https://taotoken.net/api/v1，有些客户端会拼出错误路径。检查：
echo $env:OPENCODE_BASE_URL输出应该是https://taotoken.net/api。不对就改：
$env:OPENCODE_BASE_URL = "https://taotoken.net/api"报错五：reading choices或返回体解析失败
这个报错说明请求发出去了，但返回的 JSON 结构里没有choices字段。常见原因是模型 ID 写错了，或者你用的模型不支持 OpenAI 兼容格式。确认你填的 Model ID 在 TaoToken 的模型列表里存在。如果你用的是 Claude 系列，注意它的返回格式和 OpenAI 略有不同，OpenCode 一般会自动处理，但 Model ID 必须写对。
报错六：OAuth 相关报错
如果你在 OpenCode 里配了 OAuth 登录，报OAuth token expired或invalid_grant，说明 token 过期了。重新走一遍登录流程，或者改用 API Key 方式。API Key 方式更简单，不涉及 token 刷新。
报错七：using namespace报错
这个在第 2 节提过，profile 里如果有using namespace语句，必须在文件最顶部。打开$PROFILE检查，把这两行挪到第一行：
using namespace System.Management.Automation using namespace System.Management.Automation.Language保存后. $PROFILE重新加载。
排查完这些，基本没有过不去的坎。如果还有问题，去 TaoToken 的接入文档看最新的配置示例，或者直接在模型对话里问一下报错含义。
6. 长期使用建议与接入入口
fnm 配好之后，日常使用其实就几个命令。fnm list看装了哪些版本，fnm install <version>装新的，fnm default <version>设默认，fnm use <version>临时切。项目里放.node-version，进目录自动切，这是最省心的用法。
有一个习惯建议你养成：每次新开项目，先echo "22" > .node-version把版本锁住。这样团队里其他人 clone 下来，只要装了 fnm，进目录就自动用对版本，不会出现「我这能跑你那报错」的情况。OpenCode 这类工具对 Node 版本敏感，锁版本能省掉很多沟通成本。
如果你要长期用 OpenCode 做编码或 Agent 任务，建议把 API Key 和 Base URL 写进 profile，省得每次手动设。Key 在 TaoToken 控制台创建，地址是https://taotoken.net/console/api-keys。接入文档在https://taotoken.net/doc，里面有各语言的配置示例。想先试试模型效果，可以直接用模型对话页面https://taotoken.net/chat。如果打算长期跑编码任务，Coding Plan 更划算，入口在https://taotoken.net/coding-plan。
最后提醒一句：fnm 的--use-on-cd依赖 profile 加载，如果你用 VS Code 的集成终端，确保它启动的是 PowerShell 而不是 cmd。VS Code 里按Ctrl+Shift+P，搜「Terminal: Select Default Profile」，选 PowerShell。这样你在编辑器里开终端，fnm 的自动切换也能生效，OpenCode 在项目里跑就不会因为版本问题掉链子。
