Windows 开源项目部署评估与决策清单（完整版）

【EPGF 白皮书】路径治理驱动的多版本 Python 架构------ Windows 环境治理与 AI 教学开发体系

一次搭好、终身不乱Windows Python 环境治理（EPGF）系列总览 / 阅读路线图 $目录$

2025 年电脑硬件选购指南量表（"硬件卡尺"）

家用或办公 Windows 电脑玩人工智能开源项目配备核显的必要性（含 NPU 及显卡类型补充）

GitHub 项目部署全攻略：从踩坑排查到稳定上线的20个关键环节

【没有轮子就自己造】BasicSR Windows 编译安装教程 Python3.14 CUDA13.0

Windows 本地编译 CUDA Extension Wheel 完全指南

Windows 多版本 CUDA + cuDNN 环境配置完全指南
 【CUDA GPU 支持安装全攻略】PyTorch 深度学习开发者指南

PyTorch 的 CUDA GPU 支持 · 安装五条铁律（最新版 2025 修订）（适用于所有用户）

"100% 成功的 PyTorch CUDA GPU 支持" 安装攻略

验证PyTorch深度学习环境Torch和CUDA还有cuDNN是否正确配置的命令

在 WSL2-NVIDIA-Workbench 中安装Anaconda、CUDA 13.0、cuDNN 9.12 及 PyTorch（含完整环境验证）

新！在 podman-machine-default 中安装 CUDA、cuDNN、Anaconda、PyTorch 等并验证安装

Windows 开源项目部署评估与决策清单（自用 & 完整版）

文档说明：本清单基于 Windows Windows 11 环境整理，涉及的工具版本和命令以 2024--2026 年为参考基线。随着生态演进，部分细节可能需要结合实际情况调整。

核心原则：在动手之前，先判断"值不值得做"和"能不能做"，避免盲目投入时间成本。

写在前面：这份清单从哪里来

这份清单不是从教程里整理出来的------它来自在 Windows 原生环境下长期折腾 AI 工程的实际经验积累。

作者在 Windows 11 + RTX 3090 的单机环境下，拒绝把 Docker 当成"遇到麻烦就套容器"的逃生出口，坚持完成了大量原生部署与源码编译工作，覆盖范围包括但不限于：

多版本 CUDA 共存与动态切换 ：系统中同时安装了 CUDA 12.6 / 12.8 / 12.9 / 13.0 / 13.1 共五个版本，并开发了 Switch-CUDA 脚本实现秒级切换，彻底解决了不同项目对 CUDA 版本强依赖的冲突问题------这个问题在 Windows 下比 Linux 棘手得多，因为 cuDNN DLL 的搜索路径逻辑与 Linux 有本质区别。

高难度 Python 扩展的 Windows 原生编译：在没有 WSL、不依赖 Linux 环境的前提下，从源码编译了一系列公认在 Windows 上"不好弄"的 CUDA 扩展，包括：

nvdiffrast（可微渲染）
diff-gaussian-rasterization（3D Gaussian Splatting 核心算子）
pytorch3d（Facebook 3D 视觉库）
simple-knn（KNN 近邻加速）
torch-cluster（图神经网络聚类算子）
SageAttention 2.2.0（基于 woct0rdho 的 Windows 移植 fork，含 Triton 适配与 dtype 回退补丁）
onnxruntime-gpu（含 cuDNN 9.x DLL 手动注入适配）
vLLM 0.16.0rc2（完整 Windows 编译，cu126 版本，含 USE_LIBUV=0 等 Windows 特有补丁）

每一个都踩过：因路径含空格导致 nvcc 报错、因 CUDA_HOME 未对齐导致编译器找错工具链、因架构参数缺失导致 Tensor Core 未启用等真实坑点。最终形成了一套可复现的编译 SOP：subst Z: 挂载无空格路径、四个 CUDA 环境变量统一指向 Z:、在 VS 2022 Developer Shell x64 下执行 pip wheel、TORCH_CUDA_ARCH_LIST=8.6 精准匹配 sm_86 架构。

去 Docker 的本地化部署：ComfyUI（含 260+ 个自定义节点）、FaceFusion 3.x、vLLM、DeepFaceLab 等项目均在 Windows 原生 venv 中稳定运行，而非依赖容器隔离。这意味着遇到的每一个 DLL 缺失、PATH 污染、PowerShell 执行策略拦截、进程句柄泄漏问题，都必须在 Windows 层面彻底解决，没有容器帮你兜底。

跨框架的深度调试 ：包括 Triton ptxas.exe 路径注入、xFormers 降版本修复 ComfyUI-3D-Pack 级联崩溃、rgthree-comfy 与 ComfyUI Nodes 2.0/Vue 渲染层不兼容、FaceFusion 的 onnxruntime error 999 与 CUDA 13.x bin\x64\ 路径变更、项目的源代码修改适配、BitNet 源码修改、算子编译等，这些问题在 Issues 里往往没有 Windows 下的现成答案，只能通过阅读源码和逐层追溯 DLL 加载路径来定位。

上述经验均已整理为系列博文，发布于 CSDN 技术博客（aicity），覆盖从零搭建 Windows AI 开发环境的完整路径。

所以这份清单想解决的，是那种"网上的教程全是 Linux 的，Windows 上一跑就报错，不知道该继续还是放弃"的困境。 它不保证让所有项目都能跑起来，但它能帮你在 5 分钟内判断值不值得继续、在遇到障碍时知道下一步往哪走、在该止损时不拖泥带水。

阶段零：快速决策框架 ------ 5 分钟初筛机制

在深入任何步骤前，先用以下标准进行快速可行性评估。以下为参考性判断框架，不应机械套用：

评估维度	绿灯（推荐尝试）	黄灯（谨慎评估）	红灯（建议暂停/换方案）
项目定位	明确标注 Windows 支持，或有跨平台声明	仅提及 Linux，但使用 Python/Node 等跨平台语言	明确声明 "Linux Only" 或大量依赖系统级调用
社区活跃度	近 3 个月有更新，Issues 有维护者回复	更新停滞 6--12 个月，但文档完整	超过 1 年无更新，Issues 堆积无人处理
硬件匹配	硬件配置达到推荐要求	略低于推荐，可尝试量化或降配	显存/内存严重不足（如 4 GB 显存运行 SDXL）
技术栈熟悉度	熟悉的技术栈（Python/Node/Electron）	需学习新技术，但有现成教程	完全陌生的底层技术，且时间有限
时间预算	预计 2--4 小时可跑通	预计 1--2 天，需查阅较多资料	预计需要一周以上深度改造

决策参考：

3 个及以上绿灯 → 继续阶段一
2 个及以上黄灯 → 先调研是否有替代方案（如 Docker 版本、WSL 方案）
出现红灯 → 建议暂停，搜索国内外媒体/社区讨论，直到记录原因至"放弃清单"，避免重复尝试

注：对于熟悉 C++/Rust 的开发者，"技术栈陌生"未必是红灯；请结合自身情况灵活判断。

阶段一：项目目标与源码审计

1.1 部署目标定义

目标类型	容忍度	技术选型建议
个人开发/测试	可容忍警告和临时修复	优先尝试原生 Windows，失败后考虑 WSL2
本地演示/原型	需稳定运行，偶发崩溃可接受	推荐 WSL2 或 Docker/Podman，保证环境一致性
生产环境	要求长期稳定	容器化或云服务器部署是更可靠的选择

经验提示：生产环境若需在 Windows 原生运行 Linux 项目，应充分评估风险，通常 WSL/容器化方案维护成本更低。
解锁新技能！Windows 11 借助 WSL - Linux 部署 GitHub 项目全攻略
 【保姆级教程】Windows + Podman 从零部署 Duix-Avatar 数字人项目
 【笔记】在 Podman Machine（Fedora 42）中安装 NVIDIA Container Toolkit 使镜像能使用GPU
新！在 podman-machine-default 中安装 CUDA、cuDNN、Anaconda、PyTorch 等并验证安装
 Podman Desktop：现代轻量容器管理利器（Podman与Docker）

1.2 源码与文档审查

入口点分析

识别所有启动脚本：app.py、main.py、run.py、gradio_demo/app.py
区分不同入口用途：根目录 app.py 常为云平台（如 Hugging Face Spaces）设计；gradio_demo/app.py 通常是本地运行的正确入口。选错入口是常见的起步错误。

依赖文件审查（关注 Windows 风险点）

查找 requirements.txt、pyproject.toml、environment.yml、setup.py
留意以下可能存在 Windows 兼容性问题的依赖：
- pycuda、nvidia-ml-py（与 CUDA 版本强绑定）
- gunicorn（在 Windows 上不受官方支持，可考虑用 waitress 替代）
- celery（常依赖 Redis，Windows 下需额外配置）
- PyTorch 的 Linux 特定编译版本
检查是否有 Dockerfile：有则可优先考虑容器化部署

社区健康度评估

在 Issues 页搜索：Windows、install、error、WSL
参考健康度指标：
- Star/Fork 比 ≥ 1:5（说明真实使用者较多）
- Issue 解决率较高（建议 ≥ 70%）
- 最近提交时间 < 3 个月

阶段二：本地环境评估与 Windows 兼容性诊断

2.1 硬件资源盘点

资源类型	检查项	Windows 特殊注意
GPU/显存	是否需要 CUDA？显存是否满足模型需求？	Windows 下 CUDA 需单独安装，与 WSL2 的 CUDA 环境相互独立
内存	建议 16 GB+，大模型建议 32 GB+	Windows 内存管理开销略高于 Linux，建议预留 15--20% 余量
磁盘	建议 SSD，预留 50 GB+ 用于模型缓存	Windows 模型缓存默认位于用户目录，注意 C 盘空间

硬件挑选

2025 年电脑硬件选购指南量表（"硬件卡尺"）
家用或办公 Windows 电脑玩人工智能开源项目配备核显的必要性（含 NPU 及显卡类型补充）

更多文章请见主页

空间管理

【打造 AI 开发环境系列】WSL 路径治理必做篇：先迁移，再开发，别让 C 盘爆满！
EPGF 新手教程 02第一次安装就不踩坑：Anaconda 正确安装与路径一次性治理------把 Python 安装在 D:\A，从此不再折腾环境变量
 Windows 开发环境部署指南：WSL、Docker Desktop、Podman Desktop 部署顺序与存储路径迁移指南
 把 C 盘从"爆红"边缘救回来：安全清理 Hugging Face 缓存的完整实战笔记
 在 NVIDIA-Workbench（WSL2-Ubuntu 22.04）中部署 SkyReels-V2 昆仑万维电影生成模型 ------ 逐命令逐输出，附模型缓存映射技巧
 告别磁盘爆红！WSL2 部署大模型将 Hugging Face / ModelScope 缓存迁移到 Windows 指定盘符（可视化）指南
 Windows 如何更改 Hugging Face 模型下载缓存位置？
Windows 如何更改 ModelScope 的模型下载缓存位置？
第3篇：软链接 mklink /D 教程：轻量缓存目录迁移利器
 【笔记】解决部署国产AI Agent 开源项目 MiniMax-M1时 Hugging Face 模型下载缓存占满 C 盘问题：更改缓存位置全流程
 基于 EPGF 架构的环境迁移复现部署及基于符号链接的模型共享解决方案------FaceFusion 3.3.2与3.4.1 模型共享方案：100GB 空间节省实践
 【2025最新】ComfyUI 0.4.55+ 版本共享 Stable Diffusion WebUI 模型配置指南（解决 extra_model_paths.yaml 失效问题）
ComfyUI for Windwos与 Stable Diffusion WebUI 模型共享修复
 Ollama更改安装路径、巧用符号链接更改模型下载路径的正确方法WIN系统

更多文章请见主页

2.2 软件环境配置

【EPGF 白皮书】路径治理驱动的多版本 Python 架构------ Windows 环境治理与 AI 教学开发体系
 一次搭好、终身不乱Windows Python 环境治理（EPGF）系列总览 / 阅读路线图 $目录$

Python 版本管理

严格核对项目所需的 Python 版本（如 3.10、3.11）
Windows 下版本过高或过低均可能导致预编译包（Wheel）不兼容
推荐使用 EPGF架构或 pyenv-win 及 conda 管理 Python 多版本

Windows 多版本 Python 管理（EPGF 架构）

Python 多版本环境治理理念驱动的系统架构设计------三维治理、四级隔离、五项自治原则（路径治理升级修订 V 2.0 版）

包管理器选择

复制代码

项目涉及 C++ 库（PyTorch/SciPy/NumPy）？
├── 是 → 优先使用 EPGF架构/conda（底层依赖处理更稳健）
└── 否 → 使用 pip + virtualenv（更轻量）

项目需要 GPU 加速？
├── 是 → pip 安装 torch+cuda 版
├        conda 安装 cudatoolkit，注意版本匹配
└── 否 → pip 安装 CPU 版本即可

虚拟环境（强烈建议）

【零基础】Python 多版本虚拟环境管理与隔离实战------支持 Anaconda、Poetry、Pipenv、venv、uv、Hatch、PyCharm、VS Code 的统一工具链方案

为每个项目创建独立虚拟环境（.venv），避免依赖污染
Windows 激活命令：.\.venv\Scripts\Activate.ps1（PowerShell）或 .venv\Scripts\activate.bat（CMD）

PowerShell 执行策略问题：

复制代码

# 若无法激活虚拟环境，以管理员身份运行（注意该设置会降低安全限制）：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

参考：PowerShell 执行策略说明 - Microsoft 文档

2.3 网络环境评估

网络场景	检测方法	Windows 解决思路
Hugging Face 无法访问	`curl https://huggingface.co`	设置 `HF_ENDPOINT=https://hf-mirror.com`
GitHub 下载慢	`git clone` 速度 < 50 KB/s	使用镜像站或配置 Dai 理
pip 安装慢或超时	`pip install` 卡住	使用清华镜像：`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple`

阶段三：Windows 部署路径决策

这是最关键的阶段------选择不匹配的部署路径往往是大量时间浪费的根源。

【笔记●避免C盘爆满】Windows 系统开发环境存储路径迁移全规划参考清单
 【理念●体系】Windows AI 开发环境搭建实录：六层架构的逐步实现与路径治理指南
 【理念●体系】路径治理篇：打造可控、可迁移、可复现的 AI 开发路径结构

3.1 部署路径选择矩阵

项目特征	推荐方案	复杂度	性能损失参考	维护成本
纯 Python，无系统依赖	原生 Windows	⭐⭐	极低	低
含 `.sh` 脚本，依赖 Linux 命令	WSL2	⭐⭐⭐	< 5%（多数场景）	中
复杂依赖，多服务架构	Docker Desktop	⭐⭐⭐⭐	< 10%（视 I/O 而定）	低
生产环境，需长期稳定	Docker / 云服务器	⭐⭐⭐⭐⭐	0--8%	低

决策流程：

复制代码

开始
  │
  ▼
项目是否明确支持 Windows？
├── 是 → 尝试原生部署（阶段四）
└── 否 → 项目是否提供 Dockerfile？
    ├── 是 → 使用 Docker Desktop 部署
    └── 否 → 是否涉及大量 Linux 系统调用（如 /proc、epoll）？
        ├── 是 → 使用 WSL2 部署
        └── 否 → 尝试原生 Windows，预备修改脚本

3.2 WSL2 部署专项

适用场景 ：项目含大量 Linux 脚本（.sh），依赖 Linux 系统特性。

前置检查：

Windows 版本 ≥ 19041（Win10 20H1）或 Windows 11
BIOS 中已启用虚拟化（Intel VT-x / AMD-V）
安装 WSL2：wsl --install -d Ubuntu-22.04（官方文档）
如需 GPU 支持，安装 NVIDIA CUDA on WSL 驱动（注意：WSL2 使用 Windows 侧驱动，无需在 Linux 内单独装驱动）

WSL2 配置优化 （%UserProfile%\.wslconfig）：

复制代码

[wsl2]
memory=8GB          # 根据物理内存调整，建议为 Windows 保留至少 4 GB
processors=4        # 分配 CPU 核心数
swap=2GB
localhostForwarding=true

文件系统性能注意：

避免在 /mnt/c/（Windows 盘符挂载路径）下运行项目，跨文件系统 I/O 性能较差
建议将项目放在 WSL 原生文件系统：/home/username/project
从 Windows 侧访问 WSL 文件：\\wsl$\Ubuntu\home\username\project

3.3 Docker Desktop 部署专项

适用场景：项目提供 Dockerfile，或需要隔离、可复现的运行环境。

Windows 特有配置：

启用 WSL2 后端：Docker Settings → General → Use the WSL 2 based engine（Docker 官方文档）
资源分配：Settings → Resources → WSL Integration → 启用你的发行版
文件挂载建议使用 WSL2 路径（/home/user/project）而非 Windows 路径，以获得更好的 I/O 性能

GPU 支持配置 （需安装 NVIDIA Container Toolkit）：

复制代码

# docker-compose.yml 示例
services:
  app:
    image: your-image
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all

3.4 原生 Windows 移植要点

突破 Windows 编译禁区：BitNet 1-bit LLM 推理框架 GPU 加速部署编译 BitNet CUDA 算子全记录
 【独家资源】Windows 本地部署微软 BitNet b1.58： Flash Attention + CUDA GPU 加速 (sm_86) + AVX2 优化 + 1.58bit 量化
 Duix-Avatar 去 Docker Desktop 本地化完整复盘

适用场景：项目结构简单，且期望获得最佳原生性能。

常见 Linux 元素的 Windows 对应替换：

Linux 元素	Windows 替代方案
`.sh` 脚本	`.bat` 或 PowerShell 脚本
`/` 路径分隔符	`\` 或 `os.path.join()` / `pathlib.Path`
`pkill`、`killall`	`taskkill /F /IM python.exe`
`rm -rf`	`rmdir /S /Q` 或 `Remove-Item -Recurse -Force`
`export VAR=value`	`set VAR=value` 或 `$env:VAR="value"`
`#!/usr/bin/env python3` Shebang	删除该行，或使用 Python Launcher（`py` 命令）

路径处理最佳实践：

复制代码

# 推荐：使用 pathlib 跨平台处理路径
from pathlib import Path
model_path = Path(__file__).parent / "models" / "weights.pth"

# 避免硬编码：
# model_path = "models/weights.pth"    # 仅 Linux/macOS
# model_path = "models\\weights.pth"   # 仅 Windows

参考：pathlib 官方文档

阶段四：依赖与配置决策

4.1 依赖安装策略

基础安装：

复制代码

pip install -r requirements.txt

# 若存在冲突，使用约束文件
pip install -r requirements.txt -c constraints.txt

冲突处理思路：

复制代码

遇到 ImportError / TypeError？
├── 定位冲突库（如 gradio vs fastapi 版本不兼容）
├── 策略一：版本锁定
│   └── pip install gradio==3.50.2
├── 策略二：降级修复（开源项目中较为常用）
│   └── 降级至项目适配的稳定版
└── 策略三：运行时补丁（Monkey Patch）
    └── 在本地代码中动态修复库的行为

Windows 常见依赖注意事项：

pywin32：需匹配 Python 版本和系统位数（下载页）
torch：需指定 CUDA 版本，示例：pip install torch --index-url https://download.pytorch.org/whl/cu121（PyTorch 官方安装指引）
tensorflow：2.11 起官方停止支持 Windows 原生 GPU，更高版本建议使用 WSL2 或 DirectML 后端（TensorFlow Windows 说明）

4.2 模型与资源完整性

Git LFS 占位符问题

确认模型是首次运行自动下载，还是需要手动放置
检查下载文件的实际大小------Git LFS 配置不当时，下载的可能只是几 KB 的指针文件，而非真实权重

模型缓存路径（Windows 特有问题）

框架	默认缓存路径	修改方法
Hugging Face	`C:\Users\<user>\.cache\huggingface`	设置 `HF_HOME` 环境变量
PyTorch	`C:\Users\<user>\.cache\torch`	设置 `TORCH_HOME` 环境变量
TensorFlow/Keras	`C:\Users\<user>\.keras`	设置 `KERAS_HOME` 环境变量

建议将模型缓存迁移至数据盘，避免 C 盘容量不足：

复制代码

[Environment]::SetEnvironmentVariable("HF_HOME", "D:\models\huggingface", "User")

注：该命令写入注册表用户环境变量，重启终端后生效。

4.3 Windows 特有配置（Electron/FFmpeg 专项）

FFmpeg 跨平台路径处理：

复制代码

import { app } from 'electron';
import os from 'os';
import path from 'path';

const platform = os.platform();
const isWin = platform === 'win32';
const isPackaged = app.isPackaged;

const basePath = isPackaged
  ? path.join(process.resourcesPath)        // 打包后
  : path.join(app.getAppPath(), 'resources'); // 开发时

const ffmpegPath = path.join(
  basePath,
  'ffmpeg',
  platform,
  `ffmpeg${isWin ? '.exe' : ''}`
);

electron-forge 打包配置示例：

复制代码

// forge.config.js
const os = require('os');
const platform = os.platform();

module.exports = {
  packagerConfig: {
    extraResource: [`./resources/ffmpeg/${platform}`],
    asar: true,
    asarUnpack: ['**/ffmpeg/**']  // 确保二进制不被打进 asar
  }
};

Electron + FFmpeg 常见 Windows 问题：

问题现象	可能原因	解决思路
`ffmpeg_common.cc Unsupported pixel format: -1`	FFmpeg 版本不兼容或编译参数缺少像素格式支持	使用官方静态编译版，确认像素格式列表（FFmpeg 官方下载）
`socket hang up`（语音合成 API）	网络超时或本地服务未就绪	检查防火墙规则，增加超时配置，先单独测试服务连通性
开发环境正常，打包后找不到 FFmpeg	路径解析错误	改用 `process.resourcesPath` 替代相对路径

阶段五：运行与全链路验证

5.1 启动参数参考

参数	作用	Windows 注意
`--device cuda`	使用 GPU 推理	确保 CUDA 和 cuDNN 已正确安装
`--share=False`	禁用 Gradio 公网穿透	`--share=True` 可能因 Windows 防火墙导致连接不稳定
`--server_name 0.0.0.0`	监听所有网卡	Windows 防火墙会弹出授权提示，需允许

5.2 分层验证

层级 1：服务可用性

终端显示 Running on local URL: http://127.0.0.1:7860
无阻塞性 Error（Warning 可暂时记录，后续处理）
浏览器可正常访问界面

层级 2：推理链路完整性（核心）

上传测试文件，触发完整推理流程
确认最终生成结果符合预期，而不仅是界面无报错
验证完整链路：预处理 → 模型推理 → 后处理 → 输出

层级 3：Windows 特有稳定性测试

使用含中文、空格的文件路径进行测试
持续运行 30 分钟以上，观察是否有显存泄漏
Windows 休眠唤醒后，确认 GPU 和服务仍可正常工作（这是 Windows 下的已知常见问题）

5.3 错误与警告分级

级别	处理方式	示例
Error	优先解决，阻断运行	`ModuleNotFoundError`、`CUDA out of memory`
Warning	记录，视情况处理	`FutureWarning: deprecated API`
Windows 特有 Error	优先检查路径、权限、编码	`PermissionError`、`UnicodeDecodeError`

阶段六：止损与退出策略

明确何时停止，是避免沉没成本陷阱的关键。

6.1 建议暂停的信号

以下情况出现时，建议优先考虑替代方案，而非继续深挖：

已投入 4 小时以上，仍未解决基础环境问题
确认显存/内存不足，且量化、裁剪等手段均无法满足需求
依赖自行编译自定义 CUDA 算子等较为复杂的底层工作
Issues 中相同问题超过 3 个月无人回复
存在功能相当且 Windows 适配更好的替代项目
关键代码没有真正开源

6.2 退出前的梯度尝试

尝试顺序	方案	参考时间
1	搜索"项目名 + Windows + WSL2"，查找社区解决方案	15 分钟
2	寻找社区维护的 Windows Fork	30 分钟
3	尝试 Docker 版本	1 小时
4	在 Linux 云服务器上部署	2 小时

6.3 放弃记录模板

记录原因，避免未来重复踩坑：

复制代码

项目：[项目名称]
GitHub：[链接]
记录日期：[日期]
放弃原因：[硬件不足 / 依赖复杂 / 无 Windows 支持 / 时间成本过高 / 未开源代码 /其他]
尝试过的方案：[原生 / WSL2 / Docker / 云服务器]
最终替代方案：[使用的其他项目或方法]

阶段七：运维与知识沉淀

7.1 资源清理

复制代码

# 清理残留 Python 进程（显存泄漏后使用）
taskkill /F /IM python.exe

# 查找并释放被占用的端口
netstat -ano | findstr :7860
taskkill /PID <PID> /F

# 释放 WSL2 内存（若 WSL 占用不释放）
wsl --shutdown

7.2 脚本化沉淀

将成功部署的步骤固化为脚本，减少重复劳动。

setup.bat（Windows CMD 原生）：

复制代码

@echo off
echo Creating virtual environment...
python -m venv .venv
call .venv\Scripts\activate.bat

echo Installing dependencies...
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# or
pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu126

echo Setting environment variables...
set HF_HOME=D:\models\huggingface

echo Starting application...
python app.py --device cuda --share=False

setup.ps1（PowerShell，含 WSL2 环境检测）：

复制代码

# 检测当前运行环境
if ($env:WSL_DISTRO_NAME) {
    Write-Host "Running in WSL2: $env:WSL_DISTRO_NAME"
    if (-not (Test-Path ".venv")) { python3 -m venv .venv }
    . ./.venv/bin/activate     # WSL2/Linux 激活方式
} else {
    Write-Host "Running in Windows native"
    if (-not (Test-Path ".venv")) { python -m venv .venv }
    .\.venv\Scripts\Activate.ps1  # Windows 激活方式
}

pip install -r requirements.txt
python app.py

原始版本中在 Windows PowerShell 下混用了 source 命令（仅 bash/zsh 可用），已修正为条件分支。

7.3 知识沉淀建议

建议维护个人部署笔记，持续记录：

项目特定的 Windows 适配点和已知绕过方案
经过验证的版本组合（Python + PyTorch + CUDA + cuDNN）
遇到的具体报错及对应解决方法

附录：快速决策速查

场景	建议方案	参考工具/命令
项目仅支持 Linux，无 Dockerfile	WSL2	`wsl --install`（文档）
需要 GPU 加速的 AI 项目	WSL2 + CUDA	NVIDIA WSL 驱动
多服务/复杂依赖	Docker Desktop	Docker 官方安装
简单 Python 项目	原生 Windows + conda	`conda create -n env python=3.11`
含大量 `.sh` 脚本	WSL2（推荐）或 Git Bash	WSL2 兼容性更好
生产环境部署	云服务器或 Docker	阿里云 / 腾讯云 / AWS 等