vsdevshell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VsDevShell (Visual Studio Developer Shell)

VsDevShell（Visual Studio开发人员Shell）

Use this skill when you need to run Windows build tools that typically only work after a Visual Studio Developer Prompt /

VsDevCmd.bat

has been applied.

当你需要运行通常只有在打开Visual Studio开发人员提示符或执行

VsDevCmd.bat

后才能正常工作的Windows构建工具时，可以使用本技能。

When to use

使用场景

Use this skill when you see errors like:

msbuild : The term 'msbuild' is not recognized...

```
cl.exe
```
/
```
link.exe
```
/
```
rc.exe
```
not found
CMake/Ninja can’t find the MSVC toolchain

Start with

msbuild

, but the same approach applies to many VS toolchain commands.

当你遇到以下错误时，可使用本技能：

msbuild : 术语“msbuild”未被识别...

找不到
```
cl.exe
```
/
```
link.exe
```
/
```
rc.exe
```
CMake/Ninja 无法找到MSVC工具链

以

msbuild

为例，该方法同样适用于许多VS工具链命令。

Common tools that often need VS dev env

通常需要VS开发环境的工具

If you need to run any of the following, enter the VS dev shell first so PATH/Windows SDK/VC tools variables are set correctly:

Build / project tooling:
```
msbuild.exe
```
,
```
devenv.com
```
,
```
nmake.exe
```
Build systems (sometimes VS-bundled):
```
cmake.exe
```
,
```
ninja.exe
```

Packaging & signing (Windows SDK):

signtool.exe

makeappx.exe

makepri.exe

appcert.exe

Resources & manifests (Windows SDK):
```
rc.exe
```
,
```
mt.exe
```
,
```
mc.exe
```
IDL / interop:
```
midl.exe
```
,
```
tlibimp.exe
```
,
```
tlbexp.exe
```
Binary inspection & PDB/symbol utilities (varies by installed components):
```
dumpbin.exe
```
,
```
pdbcopy.exe
```
,
```
pdbstr.exe
```
,
```
symstore.exe
```
,
```
symchk.exe
```
Driver/INF tooling (specialized; requires WDK components):
```
inf2cat.exe
```

If the user’s command references one of these tools (or a build script calls them indirectly), run the “enter dev env” step before running the command.

如果你需要运行以下任一工具，请先进入VS开发Shell，确保PATH/Windows SDK/VC工具变量配置正确：

构建/项目工具：
```
msbuild.exe
```
、
```
devenv.com
```
、
```
nmake.exe
```
构建系统（部分为VS捆绑）：
```
cmake.exe
```
、
```
ninja.exe
```

打包与签名（Windows SDK）：

signtool.exe

、

makeappx.exe

、

makepri.exe

、

appcert.exe

资源与清单（Windows SDK）：
```
rc.exe
```
、
```
mt.exe
```
、
```
mc.exe
```
IDL/互操作：
```
midl.exe
```
、
```
tlibimp.exe
```
、
```
tlbexp.exe
```
二进制检查与PDB/符号工具（取决于已安装组件）：
```
dumpbin.exe
```
、
```
pdbcopy.exe
```
、
```
pdbstr.exe
```
、
```
symstore.exe
```
、
```
symchk.exe
```
驱动程序/INF工具（专用工具，需WDK组件）：
```
inf2cat.exe
```

如果用户的命令引用了上述任一工具（或构建脚本间接调用它们），请在运行命令前执行“进入开发环境”步骤。

Key idea

核心概念

Enter-VsDevShell

updates process environment variables (PATH, INCLUDE, LIB, VSINSTALLDIR, etc.) for the current PowerShell process.

Run it in the same terminal/session where you will run
```
msbuild
```
.
In VS Code tool runners, avoid starting a brand-new shell between “enter dev env” and “build”.

To restore the original environment (the values captured when you entered), use:

```
Exit-VsDevShell
```

Enter-VsDevShell

会为当前PowerShell进程更新进程环境变量（PATH、INCLUDE、LIB、VSINSTALLDIR等）。

请在你将要运行
```
msbuild
```
的同一个终端/会话中执行该命令。
在VS Code工具运行器中，避免在“进入开发环境”和“构建”步骤之间启动全新的Shell。

如需恢复到进入时的原始环境（保存的初始值），可使用：

```
Exit-VsDevShell
```

Important: one-time per PowerShell process

重要提示：每个PowerShell进程仅需执行一次

Treat

Enter-VsDevShell

as a one-time initialization step per PowerShell process:

If you start a fresh
```
pwsh
```
/
```
powershell.exe
```
process (new terminal tab, new task invocation, new CI step, etc.) and you need VS build tools, you must call
```
Enter-VsDevShell
```
in that process.
If you reuse an existing PowerShell process where you already called
```
Enter-VsDevShell
```
, don’t call it again.
If you really need to re-enter without leaving, use
```
Enter-VsDevShell -Force
```
.
If you need a different dev environment (for example a different
```
-Arch
```
/
```
-HostArch
```
/
```
-WinSdk
```
), use a new PowerShell process and call
```
Enter-VsDevShell
```
there with the new parameters.

将

Enter-VsDevShell

视为每个PowerShell进程仅需执行一次的初始化步骤：

如果你启动了一个全新的
```
pwsh
```
/
```
powershell.exe
```
进程（新终端标签、新任务调用、新CI步骤等），且需要使用VS构建工具，则必须在该进程中调用
```
Enter-VsDevShell
```
。
如果你复用了一个已调用过
```
Enter-VsDevShell
```
的PowerShell进程，请不要再重复调用。
如果你确实需要在不退出的情况下重新进入，请使用
```
Enter-VsDevShell -Force
```
。
如果你需要一个不同的开发环境（例如不同的
```
-Arch
```
/
```
-HostArch
```
/
```
-WinSdk
```
参数），请使用新的PowerShell进程，并在其中使用新参数调用
```
Enter-VsDevShell
```
。

Prerequisite

前提条件

This skill assumes the

VsDevShell

module is installed and available on

PSModulePath

Verify availability:
```
Get-Module -ListAvailable VsDevShell
```

If it isn't present, install it from PowerShell Gallery for the current user:

Install-Module -Name VsDevShell -Repository PSGallery -Scope CurrentUser

Then import it:

```
Import-Module VsDevShell
```

Notes:

On first install, PowerShell may prompt to install the NuGet provider and/or to trust
```
PSGallery
```
.

本技能假设

VsDevShell

模块已安装且在

PSModulePath

中可用。

验证可用性：
```
Get-Module -ListAvailable VsDevShell
```

如果模块未安装，可从PowerShell Gallery为当前用户安装：

Install-Module -Name VsDevShell -Repository PSGallery -Scope CurrentUser

然后导入模块：

```
Import-Module VsDevShell
```

注意：

首次安装时，PowerShell可能会提示安装NuGet提供程序和/或信任
```
PSGallery
```
。

Parameter mapping (intent → Enter-VsDevShell)

参数映射（意图 → Enter-VsDevShell）

```
-Arch
```
: target architecture you want to build for
- Build
```
Win32
```
  →
```
-Arch x86
```
- Build
```
x64
```
  →
```
-Arch x64
```
- Build
```
ARM64
```
  →
```
-Arch arm64
```
```
-HostArch
```
: architecture of the machine running the tools
- Typical x64 Windows host →
```
-HostArch x64
```
- Typical x86 Windows host →
```
-HostArch x86
```
- Note: currently only
```
x86
```
  /
```
x64
```
  are accepted for
```
-HostArch
```
  .
```
-AppPlatform
```
: accepted for compatibility, but currently not used to build
```
VsDevCmd.bat
```
arguments.
```
-WinSdk
```
: optional Windows SDK version string (only set when the user specifies a required SDK)
```
-NoExt
```
,
```
-NoLogo
```
: optional switches to reduce startup work/noise
```
-VsInstallPath
```
: only set when targeting a specific Visual Studio installation

```
-Arch
```
：你要构建的目标架构
- 构建
```
Win32
```
  →
```
-Arch x86
```
- 构建
```
x64
```
  →
```
-Arch x64
```
- 构建
```
ARM64
```
  →
```
-Arch arm64
```
```
-HostArch
```
：运行工具的机器架构
- 典型x64 Windows主机 →
```
-HostArch x64
```
- 典型x86 Windows主机 →
```
-HostArch x86
```
- 注意：目前
```
-HostArch
```
  仅接受
```
x86
```
  /
```
x64
```
  。
```
-AppPlatform
```
：为兼容而保留，但目前不会用于构建
```
VsDevCmd.bat
```
参数。
```
-WinSdk
```
：可选的Windows SDK版本字符串（仅当用户指定所需SDK时设置）
```
-NoExt
```
、
```
-NoLogo
```
：可选开关，用于减少启动工作/输出信息
```
-VsInstallPath
```
：仅当针对特定Visual Studio安装时设置

Recommended workflow (msbuild)

VS Code / tool-runner tip

VS Code / 工具运行器提示

If your tool runner uses a fresh PowerShell process per command, run the “enter dev env” step and the build command in the same invocation, for example:

pwsh -NoProfile -Command "Import-Module VsDevShell; Enter-VsDevShell -Arch x64 -HostArch x64 -NoLogo; msbuild -version"

If your tool runner reuses a single long-lived terminal session, run

Enter-VsDevShell

once at the start of that session, then run as many build commands as you need in the same session.

如果你的工具运行器每个命令都使用全新的PowerShell进程，请将“进入开发环境”步骤和构建命令放在同一个调用中،例如：

pwsh -NoProfile -Command "Import-Module VsDevShell; Enter-VsDevShell -Arch x64 -HostArch x64 -NoLogo; msbuild -version"

如果你的工具运行器复用单个长期运行的终端会话，请在会话开始时运行一次

Enter-VsDevShell

，然后在同一个会话中运行任意数量的构建命令。

Cross-compile examples

交叉编译示例

Build Win32 from an x64 machine:

Enter-VsDevShell -Arch x86 -HostArch x64

Build ARM64 from an x64 machine:

Enter-VsDevShell -Arch arm64 -HostArch x64

在x64机器上构建Win32：

Enter-VsDevShell -Arch x86 -HostArch x64

在x64机器上构建ARM64：

Enter-VsDevShell -Arch arm64 -HostArch x64

Inspect without applying

查看配置而不应用

If you want to see what would change without modifying your current process environment:

Get-VsDevEnv -Arch x64 -HostArch x64 | Format-Table -AutoSize

如果你想查看会发生哪些更改，而不修改当前进程环境：

Get-VsDevEnv -Arch x64 -HostArch x64 | Format-Table -AutoSize

Cmdlets and common workflows

Cmdlet与常见工作流

Enter / Leave

进入 / 退出

Compute + apply VS dev environment:

Enter-VsDevShell -Arch x64 -HostArch x64

Restore original values captured at enter time:
- ```
Exit-VsDevShell
```

计算并应用VS开发环境：

Enter-VsDevShell -Arch x64 -HostArch x64

恢复进入时保存的原始值：
- ```
Exit-VsDevShell
```

Export / Import

.env

导出 / 导入

.env

文件

Export the computed delta to a standard

.env

file (UTF-8 no BOM):

Export-VsDevEnv -Arch x64 -HostArch x64 -Path .\vsdev.env -Mode Update

Apply a

.env

file in the current session:

Pipeline form:

Import-VsDevEnv .\vsdev.env | Enter-VsDevShell

Shortcut:

Enter-VsDevShell -EnvFilePath .\vsdev.env

Restore only the keys listed in the file (using the saved pre-enter snapshot):

Exit-VsDevShell -EnvFilePath .\vsdev.env

Fully piped chain (compute → export → import → apply):

powershell

Get-VsDevEnv -Arch x64 -HostArch x64 |
  Export-VsDevEnv -Path .\vsdev.env -Mode Update -PassThru |
  Import-VsDevEnv |
  Enter-VsDevShell

Notes:

This writes the computed values (including
```
PATH
```
) and will typically override whatever values your target process already has.
Loading a dotenv file varies by tool/shell. For example, in
```
bash
```
you often need
```
set -a; source ./vsdev.env; set +a
```
to export the variables to child processes.

将计算出的环境变量差异导出为标准

.env

文件（UTF-8无BOM）：

Export-VsDevEnv -Arch x64 -HostArch x64 -Path .\vsdev.env -Mode Update

在当前会话中应用

.env

文件：

管道形式：

Import-VsDevEnv .\vsdev.env | Enter-VsDevShell

快捷方式：

Enter-VsDevShell -EnvFilePath .\vsdev.env

仅恢复文件中列出的键（使用保存的进入前快照）：

Exit-VsDevShell -EnvFilePath .\vsdev.env

完整管道链（计算 → 导出 → 导入 → 应用）：

powershell

Get-VsDevEnv -Arch x64 -HostArch x64 |
  Export-VsDevEnv -Path .\vsdev.env -Mode Update -PassThru |
  Import-VsDevEnv |
  Enter-VsDevShell

注意：

该操作会写入计算后的值（包括
```
PATH
```
），通常会覆盖目标进程已有的值。
加载dotenv文件的方式因工具/Shell而异。例如，在
```
bash
```
中，你通常需要执行
```
set -a; source ./vsdev.env; set +a
```
才能将变量导出到子进程。

GitHub Actions (

GITHUB_ENV

)

GitHub Actions（

GITHUB_ENV

）

In GitHub Actions,

$env:GITHUB_ENV

is a standard env file shared across steps. Update it so later steps inherit the VS dev environment:

Export-VsDevEnv -Arch x64 -HostArch x64 -Path $env:GITHUB_ENV -Mode Update

$env:GITHUB_PATH

is available and you want PATH handled there, use:

Export-VsDevEnv -Arch x64 -HostArch x64 -Path $env:GITHUB_ENV -Mode Update -PathMode GitHubPath

Apply it in the current step/session (optional):

Enter-VsDevShell -EnvFilePath $env:GITHUB_ENV

在GitHub Actions中，

$env:GITHUB_ENV

是跨步骤共享的标准环境文件。更新它以便后续步骤继承VS开发环境：

Export-VsDevEnv -Arch x64 -HostArch x64 -Path $env:GITHUB_ENV -Mode Update

如果

$env:GITHUB_PATH

可用，且你希望在其中处理PATH，请使用：

Export-VsDevEnv -Arch x64 -HostArch x64 -Path $env:GITHUB_ENV -Mode Update -PathMode GitHubPath

在当前步骤/会话中应用（可选）：

Enter-VsDevShell -EnvFilePath $env:GITHUB_ENV

Notes

注意事项

Windows only (relies on
```
%COMSPEC%
```
and Visual Studio's
```
VsDevCmd.bat
```
).
If
```
msbuild
```
still isn’t available after enabling the environment, the installed Visual Studio workload may be missing MSBuild/VC tools.
```
AppPlatform
```
is currently accepted but not used to build
```
VsDevCmd.bat
```
arguments.

仅支持Windows系统（依赖
```
%COMSPEC%
```
和Visual Studio的
```
VsDevCmd.bat
```
）。
如果启用环境后
```
msbuild
```
仍不可用，可能是已安装的Visual Studio工作负载缺少MSBuild/VC工具。
```
AppPlatform
```
目前仅为兼容而保留，不会用于构建
```
VsDevCmd.bat
```
参数。

vsdevshell

Original

Translation

VsDevShell (Visual Studio Developer Shell)

VsDevShell（Visual Studio开发人员Shell）

When to use

使用场景

Common tools that often need VS dev env

通常需要VS开发环境的工具

Key idea

核心概念

Important: one-time per PowerShell process

重要提示：每个PowerShell进程仅需执行一次

Prerequisite

前提条件

Parameter mapping (intent → Enter-VsDevShell)

参数映射（意图 → Enter-VsDevShell）

Recommended workflow (msbuild)

推荐工作流（msbuild）

VS Code / tool-runner tip

VS Code / 工具运行器提示

Cross-compile examples

交叉编译示例

Inspect without applying

查看配置而不应用

Cmdlets and common workflows

Cmdlet与常见工作流

Enter / Leave

进入 / 退出

Export / Import
`.env`

导出 / 导入
`.env`
文件

GitHub Actions (
`GITHUB_ENV`
)

GitHub Actions（
`GITHUB_ENV`
）

Notes

注意事项

vsdevshell

Original

Translation

VsDevShell (Visual Studio Developer Shell)

VsDevShell（Visual Studio开发人员Shell）

When to use

使用场景

Common tools that often need VS dev env

通常需要VS开发环境的工具

Key idea

核心概念

Important: one-time per PowerShell process

重要提示：每个PowerShell进程仅需执行一次

Prerequisite

前提条件

Parameter mapping (intent → Enter-VsDevShell)

参数映射（意图 → Enter-VsDevShell）

Recommended workflow (msbuild)

推荐工作流（msbuild）

VS Code / tool-runner tip

VS Code / 工具运行器提示

Cross-compile examples

交叉编译示例

Inspect without applying

查看配置而不应用

Cmdlets and common workflows

Cmdlet与常见工作流

Enter / Leave

进入 / 退出

Export / Import .env

导出 / 导入 .env 文件

GitHub Actions (GITHUB_ENV)

GitHub Actions（GITHUB_ENV）

Notes

注意事项

Export / Import
`.env`

导出 / 导入
`.env`
文件

GitHub Actions (
`GITHUB_ENV`
)

GitHub Actions（
`GITHUB_ENV`
）