Windows 下 .venv 激活脚本深度定制：同时注入 PyTorch 调试日志与国内网络加速通道
——从“能跑”到“好调”的完整工程化方案

一、为什么非得改激活脚本？

1. 重复劳动最耗时
   每次打开终端都要敲四五行 set/export，人脑就是不可靠的剪贴板。

2. 环境隔离最怕“漏删”
   手动 set 的全局变量在关闭终端前一直存在，极易在下一个项目里造成版本冲突。

3. 团队协作最怕“不一致”
   新人克隆代码后，因为少配一个变量，导致同样的脚本别人能跑他报错。
   把配置写进 activate.* 后，以上三件事一次性解决：进入 .venv 自动加载，退出 .venv 自动卸载，脚本随仓库同步，CI 也能直接复现。

---

---

二、核心原理：activate 到底做了什么？

activate.bat 只做三件小事：

1. 把 Scripts 目录插到 PATH 最前；

2. 设置 VIRTUAL_ENV 变量，方便 pip 装包时找对位置；

3. 在 CMD 里定义一个 deactivate 函数，用于回退 PATH 与变量。

PowerShell 版同理，只是语法换成 $env:。
因此“追加自定义变量”不会破坏原有逻辑，只要保证在文件末尾插入、并用 deactivate 时自动清除即可。官方脚本已经帮我们写好了“变量回退”逻辑，我们只需追加。

---

---

三、一步一步动手改

1. 创建纯净 .venv

   python -m venv .venv

   建议把 venv 目录写进 .gitignore，但把 activate-custom.bat 与 activate-custom.ps1 模板保存到 /scripts 并入库，方便团队一键覆盖。
    

2. 备份官方脚本
   复制一份 activate.bat → activate-backup.bat，万一改崩可回滚。
    

3. 追加 PyTorch 调试段
   在 activate.bat 末尾加入：

   :: =====  PyTorch 调试日志  =====
   set "TORCH_LOGS=+dynamo,+aot,+graph,+output_code"
   set "TORCHDYNAMO_VERBOSE=1"
   :: 想看 C++ 端栈帧再打开下一行
   :: set "TORCH_SHOW_CPP_STACKTRACES=1"

   说明：

   • +dynamo 是最小可用集合；

   • 若做 torch.compile 性能调优，可再追加 +aot 与 +graph；

   • 变量值用双引号包裹，防止路径含空格崩溃。
      

4. 追加网络加速段
   国内场景分两种：

   • 已有本地加速工具（C****、v2****）→ 直接指到回环端口；

   • 无工具 → 把 https_proxy 指向清华/阿里 PyPI 镜像域名，走“镜像+代理”混合模式。
     示例：

   :: 本地工具监听 7897
   set "http_proxy=http://127.0.0.1:7897"
   set "https_proxy=http://127.0.0.1:7897"
   :: 若用镜像，可再写一行
   set "PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple"

   注意：

   • 端口与工具侧配置保持一致；

   • 如果公司内网有自签证书，再加 set "PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn"。
     
      

     

5. PowerShell 版对称改造
   打开 activate.ps1 末尾：

   # =====  PyTorch 调试日志  =====
   $env:TORCH_LOGS = "+dynamo,+aot,+graph"
   $env:TORCHDYNAMO_VERBOSE = "1"
   
   # =====  网络加速  =====
   $env:http_proxy  = "http://127.0.0.1:7897"
   $env:https_proxy = "http://127.0.0.1:7897"
   $env:PIP_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"

   友情提示：PowerShell 执行策略默认禁止脚本，需先

   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

6. 让“退出”时自动清理
   官方 deactivate 函数已经帮我们 set 回空值，无需额外操作；
   若你追加了自己独创的变量，例如 MY_PROJ_DEBUG=1，记得在 deactivate 里加一行：

   set MY_PROJ_DEBUG=

   否则下次再进别的 .venv 会残留。
   
    

   

---

---

四、验证：一次打通“调试+下载”

1. 调试端验证
   写一个最小 demo.py：

   import torch
   @torch.compile
   def foo(x): return x * 2
   foo(torch.randn(2,2))

   运行后应看到 [DEBUG] torch._dynamo.eval_frame.__call__: dynamo debug log 字样，说明变量生效。

2. 下载端验证

   python -m pip install --upgrade pip setuptools wheel

   若控制台出现 Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple 且下载速度≥ 5 MB/s，即成功。

3. 快速排错表

   现象	最可能原因	1 分钟自查
   pip 仍超时	代理端口错/工具未启动	`netstat -ano	findstr 7897` 看监听
   无调试日志	变量没载入	echo %TORCH_LOGS% 是否为空
   PS 报错“无法加载脚本”	执行策略受限	Get-ExecutionPolicy -List 查看

---

---

五、高阶玩法：多环境差异化配置

1. 同仓库多版本
   项目同时维护 torch1.13、torch2.2 两个分支，可建两个 venv：

   venv113\Scripts\activate.bat
   venv220\Scripts\activate.bat

   各自脚本里写死不同 PIP_INDEX_URL 与 TORCH_LOGS，切换分支即切换环境，永不串扰。

2. 一条命令生成“完全体”
   把改造过程写成 setup_venv.py：

   import venv, subprocess, shutil, textwrap
   builder = venv.EnvBuilder(with_pip=True)
   builder.create('venv')
   # 追加片段
   patch = textwrap.dedent(r'''
       set "TORCH_LOGS=+dynamo"
       set "https_proxy=http://127.0.0.1:7897"
   ''')
   with open('venv/Scripts/activate.bat','a',encoding='utf-8') as f:
       f.write('\n'+patch)

   新人入职只需：

   python setup_venv.py
   .\venv\Scripts\activate

• CI/CD 也复用
  GitHub Actions 里加一步：

  yaml

  - name: Patch venv activate
    run: |
      cat scripts/activate-append.txt >> venv/Scripts/activate.bat

  保证云端日志级别与本地一致，debug 不再“只能本地复现”。

---

---

六、安全与合规小贴士

不要把真实账号密码写进代理地址，例如 http://user:pass@ip:port，极易被扫到。

若公司内网已有统一出口，优先使用内部 Artifactory 或 Nexus，而不是各自配代理。

脚本里只留“可公开”的镜像域名，敏感端口用 127.0.0.1，防止被外部扫描。

---

---

七、总结：把“环境”也当成代码

激活脚本也是源代码，应当：

入库：模板放 /scripts，README 写明如何覆盖；

评审：MR 阶段就检查新增变量是否必要；

自动化：一键脚本 + CI 校验，保证任何时刻 git clone → setup → run 都能跑通。

当我们把调试日志、网络加速、甚至 CUDA_VISIBLE_DEVICES 全部固化进激活脚本后，

就会发现——

“在我电脑能跑”终于不再是玄学，而是工程常识。祝调试愉快，日志常亮！

---

---

八、参考文献

venv --- 虚拟环境的创建

在Windows上使用 Python

PyTorch 文档

Lib/venv/scripts/nt/activate.bat

学习 Windows服务器 Windows命令 set (环境变量)

学习 PowerShell about_Environment_Variables

Welcome to the PyTorch developer's wiki!

介绍如何创建和使用PowerShell配置文件

Lib/venv/__init__.py

使用pip和venv在虚拟环境中安装软件包