不管你是刚从Linux迁移过来，还是第一次碰深度学习项目，在Windows 11上用VSCode和Conda把Depth-Anything-3跑起来这件事，远没有想象中那么可怕，但也没有短视频里三条命令那么轻松。这个项目做的是单目深度估计，输入一张普通RGB图，输出每个像素的深度图，在机器人、自动驾驶、三维重建、短视频特效里都很常见。
我最近在Windows 11上完整部署了一遍Depth-Anything-3，从装Anaconda到跑通推理脚本，前前后后踩了十几个坑。这篇文章不写那些花哨的原理长文，就按我实操的顺序来：环境怎么装、依赖怎么配、权重怎么下、报错怎么改，全部给到可复现的步骤。跟着走一遍，你也能在自己电脑上看到那张紫蓝渐变的深度图。
我假设你已经明白：Conda是用来管理Python虚拟环境的，VSCode是用来写代码和跑脚本的编辑器，Depth-Anything-3是一个需要PyTorch支持的开源模型仓库。这三个东西配合好，后面想换别的模型也顺手。
1. 先把这套组合的门道说清楚：Depth-Anything-3到底需要什么
1.1 单目深度估计和Depth Anything V3的核心改进
Depth Anything系列做的是Monocular Depth Estimation，也就是从单张彩色图像里推测场景中每个物体离相机的远近。V3是这个系列在2025年更新的版本，相比V2的关键变化在于引入了合成教师（synthetic teacher）的思路，不再完全依赖昂贵的真实深度真值，而是用合成数据加预训练大模型蒸馏的方式训练。实际体验下来，V3在开放场景的泛化能力更强，对透明物体、反光表面、复杂边界的处理明显更细腻，这点在室内和户外测试图上都能肉眼看出来。
它的推理流程本质上就是把图片喂给一个编码器-解码器结构的网络，编码器负责提取特征，解码器输出按像素排列的深度值，最后再做归一化渲染成可视化灰度图或伪彩色图。要想让这一系列计算在Windows上顺利执行，你至少需要Python 3.10以上、PyTorch 2.x、一份模型权重文件，以及能运行OpenCV和NumPy的Python环境。后面所有步骤实际都是在为这四件事服务。
1.2 这次部署的硬件需求与依赖构成
先说硬件底线，免得你费了半天劲最后卡在显卡上。如果你有NVIDIA独立显卡，哪怕4G显存也能跑V3的小模型，6G以上体验会舒服很多；如果是纯CPU环境，也能跑，只是推理一张512分辨率图片可能需要几十秒甚至几分钟，但用来验证流程完全没问题。内存建议16G以上，项目本身不大，模型加载和临时变量才是吃内存的大头。
软件层面，我们需要在Windows 11上装三样东西：VSCode作为IDE、Miniconda或Anaconda作为Python环境管理器，再加上Git（非必须，用浏览器下载压缩包可以跳过）。它们之间没有强行绑定关系，但用VSCode的终端配合Conda环境，能让你直接在编辑器里切换Python解释器和执行命令行，比在多个窗口来回切换高效得多。这也是我推荐这套组合而不是直接用PyCharm的原因——轻量、干净，出问题容易定位。
2. 初始化部署环境：VSCode与Conda在Windows 11下的安装要点
2.1 VSCode安装、汉化与Python插件配置
去VSCode官网下载Windows版本安装包，运行后一路下一步就行。这里有几个安装选项值得注意：在“选择其他任务”那一屏，建议把“添加到PATH”勾上，后面你想在任意终端里直接敲code命令打开项目会非常方便；“将‘通过Code打开’操作添加到文件和目录上下文菜单”也建议勾，右键就能打开项目文件夹。
装完后第一件事是汉化。打开侧边栏的扩展市场，搜索Chinese，找一个名为简体中文语言包的扩展安装，右下角会提示重启窗口。重启后界面就是中文。接下来要装的插件是Python（微软官方出品）、Pylance和Python Debugger，前两个负责语法提示和类型检查，第三个用来调试脚本。装完Python插件后，VSCode会自动扫描系统里已经安装的Python解释器，包括稍后Conda创建的虚拟环境也会被识别到，左下角状态栏会显示当前解释器路径，点击就能切换。
一个容易翻车的小细节：如果你用PowerShell作为VSCode集成终端，装完Conda后直接敲conda命令，很可能会提示“无法识别‘conda’”。这不是错代码，只是PowerShell还没加载Conda的初始化脚本。后面我会在Conda装完后补上对应的初始化命令。
2.2 Conda选型与安装路径的几个决策点
Conda有两个常见发行版：Anaconda全家桶和Miniconda轻量版。对Depth-Anything-3这个项目来说，Miniconda足够，因为项目依赖主要是pip包，Conda只负责创建隔离的Python环境，不需要Anaconda预装的那几百个科学计算包。Anaconda也不是不行，只是装了之后磁盘占用大，启动慢，换源和排查问题时更容易出现包冲突。
安装时，安装界面有一个“Add Anaconda to my PATH environment variable”的选项，新版安装器默认不勾选，而且会提示你这样做可能导致其他软件冲突。但如果不勾选，后面在VSCode终端里使用conda命令又需要额外配置。我的实际做法是：安装时保持默认不勾选，装完以后通过Conda自带的Anaconda Prompt做初始化，再把Anaconda Prompt设为VSCode默认终端。这样既避开PATH污染，又能在编辑器里正常用conda命令，两全其美。
安装路径一定要避免中文和空格，比如C:\Users\你的用户名\miniconda3里如果用户名是中文，后续某些编译型Python包会出现奇怪的编码错误。路径选择时尽量让它落在纯英文的目录下，比如D:\DevTools\miniconda3。
2.3 环境变量与镜像源配置，避免安装时卡死
Windows 11安装完Conda后，需要在Anaconda Prompt（或已初始化的终端）里执行conda init，这样PowerShell和CMD才能识别conda命令。这一步执行完后，重新打开VSCode，在终端里输入conda --version，能输出版本号就说明环境变量和初始化都生效了。
接下来强烈建议立刻换源。Conda默认连接官方源，在国内拉包经常几百KB每秒，遇到大包直接超时。我用的是清华源，在终端里依次执行：
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes同时把pip的源也换成国内镜像：
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/simple这一步能帮你少等好几个小时的下载时间。换完源之后，如果后续安装包时出现404，多半是.condarc配置文件里残留了旧路径，可以用conda clean -i清掉索引缓存再继续。
有一个和Conda官方文档不完全一致但实际排障很有效的经验：如果conda install时不断报连接错误或找不到包，先别急着加channel，到用户目录下找到.condarc文件，把channels里重复的旧地址删掉，只保留一份具体到pkgs的地址，然后重试。我在新装好的Windows 11上遇到过一次清华源404，就是旧版本残留了conda-forge和free两个源混在一起，清理后才恢复正常。
3. 创建虚拟环境与安装深度学习依赖
3.1 用Conda创建Depth-Anything-3专用环境
打开VSCode终端，执行以下命令创建Python 3.11的独立环境。之所以指定3.11，是因为Depth-Anything-3的依赖在3.10到3.12上都能兼容，但3.13某些轮子还没跟上，选3.11最稳：
conda create -n depthv3 python=3.11 -y看到“To activate this environment”字样后，激活它：
conda activate depthv3此时终端行首应该出现(depthv3)，说明已经进入虚拟环境。一个高频问题是：有些人在CMD里能激活，但换到PowerShell就报错。这是因为PowerShell执行策略限制了conda的激活脚本。解决办法是在PowerShell里执行一次：
conda init powershell然后关闭并重新打开终端，PowerShell前缀前会出现(base)。每次打开新终端先activate depthv3再操作，就不会出现解释器指向系统Python的问题。
3.2 PyTorch的CUDA版本选择与CPU兜底方案
这个项目跑的是PyTorch框架，所以在安装项目其他依赖之前，得先搞定torch和torchvision。如果你有NVIDIA显卡，打开CMD或PowerShell输入：
nvidia-smi看右上角“CUDA Version”，比如显示12.1，就要装适配CUDA 12.x的PyTorch版本。安装命令以官方为准时，我这边当时使用的是：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121注意这里不是Conda install，权重文件直接从PyTorch官方源拉取比较省事。如果你没有NVIDIA显卡，或者压根不想碰CUDA，直接装CPU版本：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpuCPU版本推理速度确实慢，但好处是省去一切驱动和CUDA动态库问题。我第一次跑通整个流程用的就是CPU版，方便确认项目本身没问题，之后再切换GPU版。
装完后一定要验证一下torch是否真正识别到了CUDA，这一步不能省。在终端里运行：
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"如果输出True，说明GPU可用；如果输出False，就算你装了CUDA版也没生效，后面运行时会报设备不可用的错。这一步检查放在安装依赖之前，能帮你省掉后面90%的迷惑行为。
4. 拉取项目、下载权重并通过VSCode完成首次推理
4.1 获取源码与权重文件的三种途径
Depth-Anything-3的代码托管在GitHub上，仓库名是DepthAnything/Depth-Anything-V3。最直接的方式是在终端里：
git clone https://github.com/DepthAnything/Depth-Anything-V3.git没有装Git的话，也可以直接在GitHub网页上把它打包成ZIP下载，解压后放到一个纯英文路径下。深度学习的UNIX风格项目在Windows下最怕路径带中文或空格，我建议直接放在C:\depthv3\Depth-Anything-V3这种位置。
项目的模型权重文件默认放在checkpoints目录下，仓库里通常会给出下载地址。权重文件有好几个档位，比如v3-large、v3-small等，首次验证流程时先用小模型，下载快、吃显存少。如果你发现直接下载慢，可以试试设置一个环境变量让Hugging Face系列的下载走国内镜像：
$env:HF_ENDPOINT="https://hf-mirror.com"然后再执行仓库给的下载脚本，或者在浏览器里手动下载.pth文件放进checkpoints目录。这一步别偷懒：很多人卡在“运行模型时提示找不到权重文件”，实际上就是权重没放到正确路径，不是代码问题。
4.2 首次推理的完整命令与参数说明
进入项目根目录，先安装项目所需的其他依赖：
cd C:\depthv3\Depth-Anything-V3 pip install -r requirements.txtrequirements.txt里包含opencv-python、numpy、pillow、tqdm等常见包。装完后，在项目文件夹里放一张你想测的图片，比如cat.jpg，然后执行：
python run.py --encoder v3-large --img-path assets/examples --outdir outputs --pred-only这一条命令做的事情是：把assets/examples目录下所有图片送入模型，深度结果输出到outputs文件夹。参数说明一下：--encoder指定模型编码器尺寸，--pred-only表示只输出深度图不输出原图对比图，--img-path可以指向单张图片也可以指向文件夹。
首次运行时会看到一长串下载提示，那是它在加载模型结构或初始权重。如果终端最后出现一张输出图片的路径，说明你已经成功跑通了。打开outputs目录，里面应该有一张深度图，颜色越红（或越亮）代表越近，越蓝（或越暗）代表越远。首次推理建议用小图或较低分辨率，能明显缩短单次推理时间。
5. 全流程常见报错修复：一条条排查到根因
5.1 安装期的conda、pip与VC编译问题
我实际踩到的第一个报错是conda命令在VSCode终端里不可用，情况就是前面提到的PowerShell没初始化。这个报错通常很好判断：终端输出“conda不是内部或外部命令”，解决办法是在Anaconda Prompt里执行conda init powershell，并重启VSCode。如果重启后仍然不行，检查系统环境变量里是否包含三个路径：conda安装目录、Scripts子目录、Library\bin子目录，手动添加后重新打开终端。
第二个高频报错是pip安装慢到怀疑人生，或者直接卡住报超时。解决办法是前面配好的国内镜像，也可以在命令后面加超时参数：
pip install simplejson --timeout 60如果报错里出现“Microsoft Visual C++ 14.0 or greater is required”，说明你的系统缺少C++生成工具。某些Python包在Windows上没有预编译的wheel，必须现场编译。这时候去微软官网下载Visual Studio Build Tools，安装时勾选使用C++的桌面开发，然后把组件“Windows 11 SDK”和“MSVC v143生成工具”选上，安装完成后重启电脑再试。
5.2 运行期的CUDA、动态库与权重加载问题
运行报错里最刺眼的一类就是CUDA相关。CUDA error: no kernel image这个报错我看了三遍才明白：这表示当前PyTorch编译时用的CUDA架构和你GPU的算力不匹配，或者显卡驱动太旧。解决办法是先升级NVIDIA驱动到最新稳定版，然后用nvidia-smi确认Supported CUDA Version，再重新安装对应版本的PyTorch。升级驱动是成本最低的排查动作，很多时候能解决一半的奇怪问题。
另一个Windows特有的烦人报错是：
OMP: Error #15: Initializing libiomp5md.dll, but found libiomp5md.dll already initialized.这说明多个包（常见是NumPy、PyTorch、OpenCV）各自带了OpenMP运行时，加载时互相打架。我的解决办法是在运行脚本之前设置一个环境变量：
$env:KMP_DUPLICATE_LIB_OK="TRUE"或者在Python脚本最前面写上：
import os os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"这样做不是完美的方案，但作为本地调试完全够用。如果你想彻底解决，可以用Conda在环境里装一个nomkl包，去掉重复的MKL动态库依赖，不过会让某些数值计算慢一点点。
权重加载报错也有两种常见情况。一种提示Unexpected key(s) in state_dict，这基本是权重文件下载错了，比如拿V2的权重喂给V3的模型，解决办法是到仓库Release页面找到对应版本的.pth文件重新下载。另一种是FileNotFoundError，提示找不到checkpoints目录下的文件，这种八成是路径问题，把权重文件移到项目根目录下checkpoints文件夹里，注意文件名要一字不差。
5.3 数据与路径相关的坑
Windows上最隐蔽的坑是用户名或路径包含中文。Conda、pip、PyTorch在加载某些原生库时如果路径里出现非ASCII字符，会出现各种莫名其妙的Unicode编码错误。最干净的做法是把这个项目部署在纯英文路径下，比如C:\depthv3或者D:\AIProjects。如果系统用户名已经是中文，你可以把项目放到D盘根目录新建的英文文件夹，尽量绕开用户目录。
第二个路径相关的问题是Windows默认的长路径限制。如果你把项目解压到很深的目录层级，或者某个依赖包安装路径过长，会触发“路径太长”异常。解决办法是打开组策略编辑器，路径为计算机配置-管理模板-系统-文件系统，启用Win32长路径；或者在注册表编辑器里定位到HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem，把LongPathsEnabled设为1，重启生效。
还有一个我调试了一晚上的坑是在VSCode集成终端里能跑通的命令，换到双击脚本运行时反而报错。原因是两个环境的当前工作目录不一致。脚本里如果用了相对路径读取图片，双击运行时工作目录可能是C:\Windows\System32，自然找不到图片。解决办法是脚本开头写：
import os os.chdir(os.path.dirname(os.path.abspath(__file__)))这样不管从哪里启动，都会先切到脚本所在的目录。
6. 跑通之后的实用扩展：批量推理与性能观察
6.1 把单张推理改成批量处理
跑通单张图片后，你会自然想处理一个文件夹里的几十张图。Depth-Anything-3仓库自带的run.py已经支持输入目录路径，它会自动遍历目录下的图片。不过如果你有更自定义的需求，比如只处理指定前缀的文件、把深度图保存成16位PNG、或者打包成视频，建议写一个简单的Python脚本而不是硬改项目源码。
我用的是如下结构的脚本，由命令行参数接收文件夹路径，然后调用项目里的模型加载函数逐张推理，每处理完一张就统计一次耗时，最后把结果统一输出到一个目录：
import argparse import glob import os import time import cv2 from depth_anything_v3.dpt import DepthAnythingV3 parser = argparse.ArgumentParser() parser.add_argument("--input", type=str, required=True) parser.add_argument("--output", type=str, default="outputs") args = parser.parse_args() os.makedirs(args.output, exist_ok=True) model = DepthAnythingV3(encoder="v3-large", features=1024, out_channels=256, localhub=True) model.load_state_dict(torch.load("checkpoints/depth_anything_v3_vitl.pth")) model.eval().cuda() for img_path in glob.glob(os.path.join(args.input, "*.jpg")): img = cv2.imread(img_path) depth = model.infer_image(img, img_size=518) # 继续保存深度图...这个脚本的好处是逻辑透明，出问题可以直接定位到某个环节，而不像黑盒命令一样只能盲猜。你完全可以根据需求调整尺寸、保存格式、是否叠加原图。
6.2 几种性能兜底与调优手段
如果你只有CPU环境，跑大图会非常煎熬。我的调优思路是：先调低输入分辨率，Depth Anything的默认输入是518x518，但你可以改成384或320，速度能提升接近一倍，效果损失在可接受范围；其次是把图片缩放到短边512再推理，减少填充带来的无效计算。实测同样一张室内图，518分辨率CPU推理约40秒，384分辨率约18秒，视觉质量几乎看不出差别。
如果你有显卡但显存小，除了换小模型之外，还可以限制batch size为1，关闭多余的可视化叠加图，减少GPU显存占用。如果出现CUDA out of memory，先排查是不是有其他程序的进程还占着显存，用任务管理器关掉后重启终端再试。
跑通之后，你还可以用这份环境做很多扩展，比如给视频逐帧提取深度序列、把深度图作为点云生成的输入，或者接上自己训练的分割模型做场景理解。核心的环境依赖都是一套，只需要替换模型文件和前处理逻辑。
最后分享一个经验：遇到不认识的报错，不要急着全网搜索，先看完整堆栈的最后一两行，特别是“Error”后面的那行英文，90%的问题都能从里面直接判断出方向。Windows环境下的报错信息通常已经把根因写在明面上了，只是我们容易被前面那些长长的依赖调用栈吓到。把上面这些坑走一遍之后，再遇到其他深度学习项目在Windows上的部署问题，你的排查思路会清晰很多。
