使用Python build模块时，如何向虚拟环境添加环境变量？

问题场景 #

Windows默认编码为GBK，为了以UTF-8编码构建Python项目，在PowerShell中设置PYTHONUTF8=1环境变量后执行构建命令：

$env:PYTHONUTF8=1
python -m build --wheel

但触发报错，核心错误信息如下：

* Creating venv isolated environment...
ERROR Failed to create venv. Maybe try installing virtualenv.
·······
UnicodeDecodeError: 'gbk' codec can't decode byte 0x99 in position 2026: illegal multibyte sequence

问题根源是设置的环境变量未传入build工具创建的venv隔离环境中，虽然可以用--no-isolation参数跳过venv创建，但希望找到能将环境变量传入venv的方法。

可行方案 #

1. 设置系统/用户级环境变量 #

直接在Windows系统中把PYTHONUTF8=1配置为用户或系统级环境变量，这样所有新启动的Python进程（包括venv内的进程）都会自动继承该变量。

• 操作步骤：
  • 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
  • 在用户变量或系统变量区域点击「新建」，变量名填PYTHONUTF8，变量值填1
  • 重启PowerShell后执行构建命令即可

2. 通过build的--config-setting传递变量 #

build工具支持通过--config-setting参数向构建后端传递环境变量，直接执行以下命令：

$env:PYTHONUTF8=1
python -m build --wheel --config-setting="env:PYTHONUTF8=1"

若使用setuptools作为构建后端，也可以用以下方式传递：

python -m build --wheel --config-setting=--build-option=-E PYTHONUTF8=1

3. 手动创建venv并继承环境变量 #

手动创建venv时，当前会话的环境变量会被venv继承，之后在venv内执行构建即可：

# 设置环境变量并创建venv
$env:PYTHONUTF8=1
python -m venv .venv
# 激活venv
.\.venv\Scripts\Activate.ps1
# 安装build工具
pip install build
# 执行构建
python -m build --wheel

内容的提问来源于stack exchange，提问作者Tpinion