Windows 下使用 mise 管理开发环境

重装系统后，开发环境往往需要重新整理：Node.js 装在哪里，多个 Python 版本怎么切换，缓存能不能放到其他盘，不同项目又该如何固定版本？

这次我选择用 mise 管理语言和工具版本，在 PowerShell 7 中使用，并让 uv 负责 Python 项目的虚拟环境与依赖。

本文记录一次实际配置过程。文中的版本号是安装时的结果，不代表读者安装时的最新版本。

1. 先明确各个工具的职责

工具	负责什么
mise	安装、选择和切换 Node.js、Python 等语言及工具的版本
uv	创建 Python 虚拟环境、安装依赖、管理项目依赖与锁文件
PowerShell 7	执行命令的 Shell
Windows Terminal	承载 PowerShell 等 Shell 的终端应用
Oh My Posh	美化命令提示符，可选

mise 不会自动恢复项目依赖。安装了 Python，不等于安装了项目需要的 Python 包；安装了 Node.js，也不等于安装了项目的 node_modules。

Oh My Posh 与 mise 可以同时使用。本文已有 Oh My Posh 配置，只需追加 mise 的激活代码。

2. 规划安装与缓存目录

我采用下面的布局：

内容	位置
mise 程序本身	由 winget 管理安装位置
mise 安装的语言和工具	`D:\Dev\mise`
mise 缓存	`E:\DevCache\mise`
mise 全局配置	`$HOME\.config\mise\config.toml`
项目代码	`E:\code\项目名`
Python 项目虚拟环境	项目内的 `.venv`
uv 缓存	`E:\DevCache\uv`

盘符可以按自己的情况调整，重点是：安装语言之前先设置目录，工具数据和缓存使用不同目录。

MISE_DATA_DIR 控制 mise 管理的工具数据位置，不是 mise 程序本身的安装位置。全局配置留在用户目录，不会因此让语言也装回 C 盘。

uv 缓存和项目虚拟环境放在同一文件系统上，有利于复用文件，避免跨文件系统时退回复制操作。

参考：mise 目录说明、uv 缓存说明。

3. 安装 mise

在 PowerShell 7 中运行：

powershell
winget install --id jdx.mise --exact --source winget

这是 mise 官方推荐的 Windows 安装方式。安装完成后重新打开终端，检查：

powershell
mise --version

本次安装的 mise 版本为 2026.10.12。

参考：mise 官方安装说明。

4. 设置数据与缓存目录

在安装 Node.js、Python 等工具之前执行：

powershell
# 持久保存到当前用户的环境变量
[Environment]::SetEnvironmentVariable('MISE_DATA_DIR', 'D:\Dev\mise', 'User')
[Environment]::SetEnvironmentVariable('MISE_CACHE_DIR', 'E:\DevCache\mise', 'User')

# 同时让当前 PowerShell 窗口立即生效
$env:MISE_DATA_DIR = 'D:\Dev\mise'
$env:MISE_CACHE_DIR = 'E:\DevCache\mise'

这两组命令有不同作用：用户环境变量负责持久保存，$env: 赋值负责更新当前进程。仅保存用户环境变量，已经打开的窗口可能仍保留旧值。

目录变量应设置在启动 mise 的环境中，不要放进项目 mise.toml 的 [env]：mise 在读取项目配置之前就需要决定使用哪些目录。

如果已经在默认目录安装过工具，修改变量不会自动搬迁旧安装。本文是在安装语言前完成设置。

5. 接入 PowerShell 7

打开 PowerShell 启动配置：

powershell
notepad $PROFILE

如果启动配置尚不存在，可以先创建，避免覆盖已有文件：

powershell
New-Item -ItemType Directory -Path (Split-Path $PROFILE) -Force | Out-Null
if (-not (Test-Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE | Out-Null
}
notepad $PROFILE

在现有配置末尾加入一次：

powershell
if (Get-Command mise -ErrorAction SilentlyContinue) {
    (& mise activate pwsh) | Out-String | Invoke-Expression
}

已有的 Oh My Posh、PSReadLine 等配置继续保留，不要用上面的代码覆盖整个文件。

当前窗口可以直接执行一次激活：

powershell
(& mise activate pwsh) | Out-String | Invoke-Expression
mise doctor

之后完全退出 Windows Terminal 再重新打开，确认新窗口也能生效。

激活会让交互式 PowerShell 随项目目录更新工具环境。脚本或自动化任务可以使用 mise exec -- 命令，不必依赖交互式启动配置。

参考：PowerShell 激活说明。

6. 用 mise doctor 检查配置

初次检查时，我看到：

text
shell:
  (unknown)

dirs:
  cache: ~\AppData\Local\Temp\mise
  data: ~\AppData\Local\mise

env_vars:
  (none)

这说明当前窗口还没有读到目录变量，也没有完成 PowerShell 集成。

完成设置后，检查结果应能识别 pwsh，并显示规划的目录。本次最终输出的关键部分是：

text
shell:
  pwsh
  PowerShell 7.6.7

dirs:
  cache: E:\DevCache\mise
  data: D:\Dev\mise
  shims: D:\Dev\mise\shims

env_vars:
  MISE_CACHE_DIR=E:\DevCache\mise
  MISE_DATA_DIR=D:\Dev\mise
  MISE_SHELL=pwsh

No problems found

关于 shims：它们是转发到 mise 管理工具的命令入口，适合未执行交互式激活的使用场景。PowerShell 使用 mise activate pwsh 时，不要仅为了消除初次检查提示，就把尚未调整的 C 盘 shims 路径写死到 PATH。先完成目录设置与激活，再检查结果。

参考：mise Shell 设置。

7. 安装 Node.js 和 Python

为了兼容已有项目，我先选择 Node 22 和 Python 3.12：

powershell
mise use -g node@22 python@3.12

-g 表示设置个人全局默认。没有项目配置覆盖时，就使用这些版本。

安装后验证：

powershell
node --version
npm --version
python --version
mise current
mise which node
mise which python

本次结果为：

text
Node.js  v22.23.3
npm      10.9.9
Python   3.12.15

实际程序位于：

text
D:\Dev\mise\installs\node\22.23.3\node.exe
D:\Dev\mise\installs\python\3.12.15\python.exe

不同版本或布局下路径可能变化，应以 mise which 的输出为准，不要在脚本中长期写死安装子目录。

8. 区分“版本规则”和“当前安装版本”

本次执行 mise use -g node@22 python@3.12 后，全局配置实际保存的是：

toml
[tools]
node = "22"
python = "3.12"

因此需要区分：

22、3.12 是配置中的版本规则。
22.23.3、3.12.15 是本次解析并安装的具体版本。
版本规则不等于精确锁定，也不代表每次打开终端都会自动升级。

对于项目，建议在项目根目录固定具体版本：

powershell
cd E:\code\my-project
mise use --pin node@22 python@3.12

--pin 会将解析出的具体版本写进项目的 mise.toml。只添加项目实际需要的语言即可；纯 Python 项目不需要同时声明 Node。

项目配置可以提交到 Git。进入项目时，它会覆盖对应工具的全局默认选择。

拿到已有项目后，先查看 mise.toml，确认可信，再执行：

powershell
mise trust
mise install

参考：mise use、mise trust。

9. 通过 mise 安装 uv

继续用 mise 管理 uv 程序本身：

powershell
mise use -g uv@latest

本次安装得到 uv 0.13.1。latest 是版本选择规则，并非固定版本；需要固定时也可以使用 --pin。

接着设置缓存，并关闭 uv 自动下载 Python：

powershell
[Environment]::SetEnvironmentVariable('UV_CACHE_DIR', 'E:\DevCache\uv', 'User')
[Environment]::SetEnvironmentVariable('UV_PYTHON_DOWNLOADS', 'never', 'User')

$env:UV_CACHE_DIR = 'E:\DevCache\uv'
$env:UV_PYTHON_DOWNLOADS = 'never'

这样约定职责：mise 安装 Python，uv 管理项目环境和依赖。缺少匹配的 Python 时，先通过 mise 安装，而不是让 uv 自动再下载一套。

注意：禁用下载并不保证 uv 永远选中 mise 的解释器。机器上有多个 Python 时，可通过 --python (mise which python) 显式指定。

验证：

powershell
uv --version
uv cache dir
uv python find

本次缓存目录为 E:\DevCache\uv，找到的解释器为 mise 安装的 Python 3.12.15。

参考：uv 环境变量、uv 命令说明。

10. Python 项目的日常用法

已有 requirements.txt 的项目

进入项目目录，为项目选择 Python，然后创建虚拟环境：

powershell
cd E:\code\my-project
mise use --pin python@3.12
uv venv --python (mise which python)
uv pip install -r requirements.txt

运行脚本时，可以直接使用虚拟环境中的解释器：

powershell
.\.venv\Scripts\python.exe main.py

也可以先激活环境：

powershell
.\.venv\Scripts\Activate.ps1
python main.py

# 使用完毕后退出
deactivate

已有 pyproject.toml 和 uv.lock 的项目

先按项目要求通过 mise 选择 Python，再同步依赖：

powershell
uv sync --python (mise which python)
uv run main.py

这类项目使用 uv 的项目工作流管理依赖。不要在未确认项目 Python 要求的情况下，直接将所有项目都改成同一版本。

11. 常用命令速查

操作	命令
检查 mise 配置	`mise doctor`
查看工具和版本	`mise ls`
查看当前目录生效版本	`mise current`
查询可安装的 Node 版本	`mise ls-remote node`
只安装某个版本	`mise install node@22`
设置全局默认版本	`mise use -g node@22`
固定项目版本	`mise use --pin node@22`
安装项目声明的工具	`mise install`
查看实际 Python 路径	`mise which python`
在 mise 环境里执行命令	`mise exec -- python --version`
查看 uv 缓存位置	`uv cache dir`

如果版本与预期不一致，先检查实际命令来源：

powershell
Get-Command node,python,uv -All
mise current
mise which python

旧版 NVM、独立安装的 Python、虚拟环境以及 IDE 的解释器设置，都可能影响实际使用的版本。桌面 IDE 也未必读取 PowerShell 的启动配置，应在 IDE 中确认项目解释器，Python 项目通常选择项目的 .venv。

12. 重装时需要保留什么

优先备份这些配置与项目文件：

全局配置：$HOME\.config\mise\config.toml。
每个项目的 mise.toml，以及项目已经使用的 mise 锁文件。
Python 项目的 pyproject.toml、uv.lock 或 requirements.txt。
Node 项目的 package.json 和对应包管理器的锁文件。
PowerShell 启动配置，以及本文设置的环境变量记录。

缓存通常可以重新生成。重装后先恢复目录变量和配置，再用 mise install 恢复工具，用项目自己的包管理器恢复依赖。不要把跨机器复制整个语言安装目录，当作通用恢复方案。