1. 为什么要在内网机器上死磕离线安装先说个我自己的真实经历。前年接手一个项目客户的生产车间是纯物理隔离的内网机器装在机柜里网口都是封死的连USB口都做了策略管控。当时需要在这台Windows机器上搭一套Python开发环境用来跑产线上的数据处理脚本和几个自动化测试工具。我一开始想得很天真觉得下个安装包装一装就完事了结果发现完全不是那么回事——Python装完之后要装一堆第三方库pip install全部报连接超时VS Code装完之后一片空白连语法高亮都不给因为Python扩展根本没装上。那次我折腾了整整两天才把一套完整的离线方案跑通。后来这类需求我又碰到过好几次有做嵌入式的朋友要在无外网的工作站上调试C代码有做数据分析的同事要把环境复制到涉密机器上还有要给一批新员工批量部署标准化开发环境的。每次踩的坑都不太一样但核心逻辑是共通的离线环境的本质是把运行时依赖和构建时依赖全部提前打包好然后用一种不依赖网络的方式搬运过去。这里有个很多人一开始就想错的地方。大部分人认为离线安装就是把安装包拷过去装一下但实际上现代开发工具链的依赖是分层的尤其是VS Code加Python这套组合至少涉及四层东西第一层是基础运行时也就是Python解释器本体。第二层是编辑器本体也就是VS Code的程序文件。第三层是编辑器扩展VS Code的Python、Pylance、Jupyter这些插件。第四层是项目依赖包也就是你代码里import的那些第三方库。这四层每一层的离线处理方法都不一样而且层与层之间还有版本匹配的坑。很多教程只讲其中一层结果照着做还是会卡住。我下面会按这四层一条条拆开讲每一层都会给出我自己验证过的操作路径和踩过的具体坑。还有一点要提前说清楚离线环境的准备工作必须在有网的机器上完成而且最好是和目标机器同操作系统、同CPU架构。这一点看起来是废话但我见过太多次有人拿Linux上准备好的包往Windows上搬或者拿x86_64的轮子往ARM板子上装最后全部报错。这个原则贯穿整个流程后面每个环节我都会强调。说说这一套环境最终能达到什么效果。跑通之后目标机器上的VS Code可以正常打开Python文件、有完整的语法高亮和智能补全、能下断点调试、能跑Jupyter Notebook、能正常安装和使用你打包好的第三方库整体体验和有网环境下基本没差别。适合的读者是需要在隔离环境、内网、涉密机器或网络不稳定环境下做Python开发的工程师也包括需要批量部署标准化环境的运维人员。哪怕你之前完全没接触过离线部署跟着走一遍也能搞明白每个环节到底在干什么。2. Python解释器的离线落地从选版本到静默部署2.1 版本选择的门道为什么我建议卡在小版本号上选Python版本这件事有网的时候随便选反正不合适当场再装一个。但离线环境下版本选择要有前瞻性因为后面所有第三方库的兼容性都挂在这个版本上。我的建议是选一个比最新版落后一到两个小版本的稳定版本比如当时最新是3.13那就选3.11或者3.12。原因很实在第三方库对新版Python的适配总是滞后的尤其是那些带C扩展的库比如numpy、pandas、lxml这类它们发布的预编译wheel包就是.whl文件通常只覆盖到某个版本。你要是选了刚发布的最新版很可能在离线源里找不到对应的wheel只能自己编译而编译又要拉一堆构建工具和头文件离线环境下这是灾难。具体到版本号还有个更细的坑Python的小版本号变化会导致wheel不兼容。Python的wheel包命名里带cp311这样的标记意思是CPython 3.11。cp311的包只能装在3.11上装到3.12上会报not a supported wheel on this platform。所以离线环境里定版本的时候最好精确到3.11.x这一级比如锁定3.11.9别到时候目标是3.11.5结果准备了3.11.9的包。至于从哪拿安装包Windows上直接去python.org的下载页面找Windows installer (64-bit)Linux上一般发行版都自带或者从源码编译。这里我不推荐用那些第三方整合包虽然它们号称开箱即用但目录结构经常和标准安装不一样离线迁移的时候会出各种路径问题出了事很难排查。2.2 Windows下的静默安装参数与可选组件拿到安装包比如python-3.11.9-amd64.exe之后有网机器上装一遍当然简单但离线部署到多台机器上时一台台点安装程序太慢而且容易点到不一样的选项。这时候要用静默安装。Python的Windows安装程序支持命令行参数常用的组合是这样python-3.11.9-amd64.exe /quiet InstallAllUsers1 PrependPath1 Include_test0 Include_pip1逐项解释一下。/quiet是静默模式不弹界面。InstallAllUsers1表示给所有用户安装装到C:\Program Files\Python311下面这个很重要因为如果不指定默认是只给当前用户装路径会跑到AppData里多用户环境下其他人用不了。PrependPath1是把Python和Scripts目录加到系统PATH里这样命令行里直接敲python和pip就能用不然每次都要写全路径。Include_test0是跳过测试套件能省几十兆空间离线包本来就金贵能省则省。Include_pip1是确保装上pip虽然通常默认就有但显式写上更保险。有个坑我要单独讲PrependPath1在静默模式下有时候不会立即生效因为环境变量的刷新依赖一个通知机制。装完之后如果发现命令行里敲python还是找不到不是装错了是环境变量没刷新。新开一个命令行窗口通常就好了如果还不行注销重登或者直接去系统属性里看一眼PATH。还有Include_launcher1这个参数也值得加上它会安装py这个启动器。这个启动器在多版本共存的时候特别好用可以写py -3.11精确调用某个版本离线环境下多版本共存是很常见的这个启动器能省不少事。Linux下就简单多了如果是源码包Python-3.11.9.tgz需要先装编译依赖然后./configure --prefix/opt/python3.11 make make install。但离线环境下编译依赖本身也是个大问题编译Python需要gcc、make、zlib-devel、openssl-devel等等一堆东西。所以如果目标机器是Linux我强烈建议优先找现成的二进制包或者用系统的包管理器离线缓存功能比如在能联网的同版本机器上用apt-get install --download-only把deb包下载下来然后拷过去用dpkg -i装这比从源码编译省太多事。2.3 把pip也要离线化本地源目录的建立装完Python之后pip本身是可以用的但它默认去PyPI拉包离线环境下必然失败。解决办法是建一个本地包目录让pip从这个目录装。这里有个非常关键的参数叫--no-index意思是完全不查在线索引只用你指定的本地路径。配合--find-links指定目录命令是这样的pip install --no-index --find-linksD:\offline_pkgs numpy pandas openpyxl--no-index是必须的不加的话pip还是会在超时前尝试访问网络拖慢速度还可能报一堆错。--find-links指向的目录里放的是一堆.whl文件pip会在里面找匹配的包。那这些whl文件怎么来在有网机器上下载。最稳妥的方式是用pip download命令这个命令只下载不安装而且可以指定平台和Python版本pip download --only-binary:all: --platform win_amd64 --python-version 311 --dest D:\offline_pkgs numpy pandas这里--only-binary:all:是强制只下载二进制wheel不下载源码包。为什么强调这个因为源码包.tar.gz到了目标机器上还需要现场编译而编译又需要编译器离线环境下大概率没有。--platform和--python-version是为了下载适配目标机器的包你在Linux上下载给Windows用的包不加这两个参数就会下成Linux的。--dest指定下载目录。注意pip download如果目标包有依赖会把依赖一起下载下来这个特性非常有用。但有时候依赖的依赖会漏掉所以下载完之后最好在目标机器上装一遍缺什么再补什么。我自己的习惯是下载完之后把整个offline_pkgs目录连同Python安装包一起打包放到一个U盘或者移动硬盘里。目录结构大概长这样offline_bundle/ ├── python-3.11.9-amd64.exe ├── offline_pkgs/ │ ├── numpy-1.26.4-cp311-cp311-win_amd64.whl │ ├── pandas-2.2.2-cp311-cp311-win_amd64.whl │ └── ... └── install.bat那个install.bat是我自己写的一键脚本内容就是把静默安装和pip安装串起来执行。这个脚本的具体写法后面讲批处理的时候再展开。3. VS Code本体的搬运便携模式与配置固化3.1 用户安装器还是系统安装器这是个分岔路口VS Code有两个版本的安装器一个是User Installer用户安装器装在用户目录下一个是System Installer系统安装器装在Program Files下。有网环境下随便选但离线场景我强烈推荐用System Installer或者干脆用它的ZIP免安装版。理由是这样的User Installer装到AppData\Local\Programs下面这台机器上换一个用户登录VS Code就没了配置也是每个用户一份。而离线部署往往是给一批机器或者一台机器的多个使用场景用的用户级的安装会带来重复配置的麻烦。System Installer装完之后全机器可用配置放在统一的位置方便我一次性把配置写好然后批量复制。如果你连安装都想免掉那就用ZIP版。VS Code官网提供.zip格式的免安装包解压就能跑不写注册表。这种方式的优势是我可以把整个VS Code目录连同配置一起打包拷到目标机器上解压就完事不需要管理员权限特别适合权限受限的环境。缺点是右键菜单、文件关联这些系统集成功能没有但对于纯写代码来说影响不大。3.2 便携模式怎么开data目录的妙用说到ZIP版就不得不提VS Code的便携模式Portable Mode。这个模式很多天天用VS Code的人都不知道但对离线部署来说是个宝贝。开启方法很简单在VS Code的解压目录里和Code.exe同级的位置新建一个名字叫data的文件夹。VS Code启动的时候检测到这个data目录存在就会把用户数据、扩展、缓存全部放到这个目录里而不是放到AppData下面。这个机制的价值在于所有的环境数据都集中在一个目录树里迁移的时候直接拷整个文件夹就行配置、插件、设置全都跟着走。我在标准化部署的时候就是这么干的在有网机器上开便携模式装好所有需要的插件配好settings.json测好Python解释器路径然后把这个文件夹整体打包。目标机器上解压改一下路径相关的配置就能直接用。配置目录的结构大致是这样VSCode-Portable/ ├── Code.exe ├── data/ │ ├── user-data/ │ │ ├── User/ │ │ │ ├── settings.json │ │ │ └── snippets/ │ │ └── ... │ └── extensions/ │ ├── ms-python.python-2024.x.x/ │ ├── ms-python.vscode-pylance-2024.x.x/ │ └── ...user-data\User\settings.json是用户设置extensions目录就是你装的插件。这个结构清楚了之后后面做迁移和备份都一目了然。3.3 离线安装插件VSIX文件的获取与安装VS Code的插件在正常情况下是从市场Marketplace在线下载的离线环境下市场是打不开的。解决办法是提前把插件下载成.vsix文件然后离线安装。获取vsix文件有两种方式。第一种是在有网的VS Code里找到插件点齿轮图标选Download VSIX它会下载到本地。但这个方法需要插件页面上有这个选项不是所有插件都有。第二种更可靠是从市场网站直接搜插件进到详情页在Version History里找到想要的具体版本点下载。这种方式的好处是我能精确控制版本避免下到最新版结果和目标VS Code版本不兼容。VS Code的插件版本和VS Code本体版本之间是有兼容要求的插件的package.json里有个engines.vscode字段比如^1.80.0意思是需要VS Code 1.80以上。如果你下的插件要求1.85而目标机器上的VS Code是1.80装的时候会提示不兼容。所以在下载插件之前最好先确认目标VS Code的版本要求或者反过来先把VS Code版本定下来再挑兼容的插件版本。安装vsix的命令行方式是这样code --install-extension ms-python.python-2024.6.0.vsixcode命令在装VS Code的时候如果勾选了添加到PATH就会有ZIP版的话在bin目录下有code.cmd。如果命令行调不通也可以在VS Code界面里扩展面板右上角三个点选Install from VSIX然后选文件。Python开发必需的插件我列一下这些是必备的插件名称扩展ID作用Pythonms-python.python核心支持调试、运行、环境管理Pylancems-python.vscode-pylance智能补全、类型检查Jupyterms-toolsai.jupyterNotebook支持Black Formatterms-python.black-formatter代码格式化Pylance这个插件要注意它体积不小而且依赖Python扩展。安装顺序最好先装Python再装Pylance不然可能会有依赖警告。Jupyter插件也是个大块头如果不用Notebook可以不装能省不少空间。提示插件装完之后VS Code会在extensions目录下建对应文件夹每个文件夹里会有一个.obsolete文件或者.extension标记。如果你想确认插件是否真的装上了看这个目录比看界面更直观。3.4 插件依赖的二进制文件一个容易被忽略的坑这里要讲一个很多人会踩的坑。有些VS Code插件内部会去下载额外的二进制文件在线的时候自动下离线的时候就卡住。最典型的是Pylance它本身是个语言服务器插件包里带了一部分的二进制但某些版本会尝试下载额外的组件。Jupyter插件的一些内核管理功能也会去下东西。规避方法是在准备阶段把插件在联网环境下完整激活一遍——打开一个Python文件让Pylance完成一次索引打开一个Notebook让Jupyter把内核检测跑一遍。这样触发它把该下的东西都下到插件目录里。然后你再打包这些下载好的文件就会跟着走。我自己测试的时候就吃过这个亏插件装上了但Python文件的补全一直转圈查了半天才发现是语言服务器的一个组件没下下来。4. 项目依赖包的完整打包从离线源到跨平台兼容4.1 依赖清单怎么生成requirements.txt的正确用法前面讲了单个包的下载但实际项目里依赖是成套的而且有版本约束。这时候要用requirements.txt来管理。生成依赖清单的标准做法是在项目环境里跑pip freeze requirements.txt但这个命令有个问题它会把环境里所有包都列进去包括那些间接依赖和跟项目无关的。更精准的方式是只导出项目直接依赖或者用pipreqs这种工具扫描代码里的import语句来生成。有了清单之后下载命令变成pip download --only-binary:all: --platform win_amd64 --python-version 311 -r requirements.txt --dest D:\offline_pkgs批量下载的好处是依赖关系会被pip自动解析不会漏包。但这里有个隐蔽的坑如果某个包只有源码包没有wheel包加了--only-binary:all:会直接报错而不是跳过。这时候要单独处理这个包要么去掉这个参数让它下源码包前提是目标机器能编译要么找替代的纯Python实现。我遇到过好几次这种情况比如某个小众库只发.tar.gz。处理办法是提前在目标环境探测一遍把这类包列出来单独准备。还有一种情况是某些包虽然发了wheel但只发了特定平台的比如只有macosx的轮子没有win_amd64的这种在Windows目标机上就得找源码编译。4.2 跨平台下载的技巧--platform和--abi的配合跨平台准备包这件事说起来简单做起来容易错。因为pip download默认是按当前机器的环境来下你在Linux上跑它就下Linux的包。要下给别用的必须把目标参数显式写全。完整的参数组合是这样pip download \ --only-binary:all: \ --platform win_amd64 \ --python-version 311 \ --implementation cp \ --abi cp311 \ -r requirements.txt \ --dest D:\offline_pkgs--platform指定目标系统的架构标识常见的有win_amd64、manylinux2014_x86_64、macosx_11_0_arm64这些。--python-version是Python版本写311就是3.11。--implementation是解释器实现一般都是cpCPython。--abi是应用二进制接口通常和Python版本对应cp311。这套参数要全部写对少一个都可能下错包。--platform和--abi要匹配比如你写--platform win_amd64但--abi写成了cp311m那个m是pymalloc标记Python 3.8之后就没这个了就会报找不到合适的包。还有一个特殊的架构标识叫any专门给纯Python的包用。有些包比如requests是纯Python写的它的wheel名字里带py3-none-any意思是任何Python 3、任何平台都能用。这种包不用管--platformpip会优先选它。4.3 版本锁定的价值一次准备多次复用离线环境准备最怕的就是这次能用下次不能用。避免这个问题的方法是把版本完全锁死。pip freeze导出的清单其实是带版本号的比如numpy1.26.4。但pip download的时候如果不加约束它可能会去下一堆相关的包的最新版。为了保证一致性可以把下载和安装都基于同一个requirements.txt并且在里面把所有包都写成精确版本。更狠一点的做法是用pip-compile来自pip-tools来生成一个完全锁定版本的清单包括所有间接依赖的版本都被锁死。这样在任何机器上重现的环境都是一模一样的离线环境下这一点特别重要因为你没法在线装个新版本来试试行不行。我自己的习惯是每次给离线环境准备包的时候都记一个环境快照包含这些信息Python的精确版本号操作系统和架构所有包的精确版本下载时的完整命令这个快照存一份在项目的docs目录里下次要给别人复制环境或者过了几个月要重建环境照着快照来就行不会出现当时能跑现在跑不了的尴尬。5. 一键化部署脚本让重复劳动自动化5.1 批处理脚本的组织结构前面每一步都讲完了但如果每次部署都手动敲一遍命令那太折磨人了。我后来把这些步骤全部串成脚本一次写好到处能用。Windows下用.bat批处理Linux下用.sh。先说Windows的。脚本的整体思路是先检查Python是否已安装、版本对不对没装就静默安装然后设置环境变量再装pip包最后装VS Code和插件。写批处理有几个坑要避开。第一是管理员权限装System级别的Python和写PATH都需要管理员权限批处理开头要加权限检测echo off net session nul 21 if %errorlevel% neq 0 ( echo 请以管理员身份运行此脚本 pause exit /b 1 )这段net session是个经典技巧它能检测当前是不是有管理员权限因为普通用户跑这个命令会报错。第二是路径里有空格的问题。C:\Program Files这种路径在批处理里如果不加引号会被截断。所有涉及路径的地方都要养成加引号的习惯。第三是错误处理脚本里每执行一步都要检查%errorlevel%失败了就报错停下别让脚本一路跑到底最后报一堆无关错误。5.2 安装脚本的核心流程一个完整的安装脚本核心流程大概是这样组织的echo off setlocal enabledelayedexpansion set PYTHON_VERSION3.11.9 set PYTHON_EXEpython-%PYTHON_VERSION%-amd64.exe set OFFLINE_PKGS%~dp0offline_pkgs set VSCode_DIR%~dp0VSCode-Portable echo [1/4] 检查Python环境... python --version 2nul | findstr %PYTHON_VERSION% nul if %errorlevel% neq 0 ( echo 未检测到目标版本开始安装... %PYTHON_EXE% /quiet InstallAllUsers1 PrependPath1 Include_test0 Include_launcher1 if !errorlevel! neq 0 ( echo Python安装失败 exit /b 1 ) ) echo [2/4] 安装离线依赖包... python -m pip install --no-index --find-links%OFFLINE_PKGS% -r %~dp0requirements.txt if !errorlevel! neq 0 ( echo 依赖包安装失败请检查offline_pkgs目录 exit /b 1 ) echo [3/4] 部署VS Code... xcopy /E /I /Y %VSCode_DIR% %LOCALAPPDATA%\VSCode-Portable echo [4/4] 安装VS Code插件... for %%f in (%~dp0vsix\*.vsix) do ( %LOCALAPPDATA%\VSCode-Portable\bin\code.cmd --install-extension %%f ) echo 部署完成 endlocal这个脚本里有几个细节值得说。%~dp0是批处理的内置变量表示脚本自身所在的目录d是drivep是path用它可以保证脚本不管在哪个目录下执行都能找到同目录下的资源。setlocal enabledelayedexpansion开启延迟变量扩展这样在if块里才能用!errorlevel!而不是%errorlevel%这是批处理里的一个经典陷阱不开启的话if块里的错误码永远是进入块之前的值。findstr那段是版本检测如果已经装了目标版本就跳过安装能避免重复装。xcopy /E /I /Y是复制目录/E包含空目录/I是如果目标是目录就当作目录处理/Y是覆盖不提示。5.3 配置文件的路径修正最容易忘的一步脚本跑完环境装好了但这时候VS Code里的Python解释器路径大概率还是错的因为settings.json里如果写死了绝对路径换台机器就失效了。settings.json里和Python相关的配置主要是这几项{ python.defaultInterpreterPath: C:\\Program Files\\Python311\\python.exe, python.analysis.typeCheckingMode: basic, python.formatting.provider: black, editor.formatOnSave: true, files.autoSave: afterDelay }python.defaultInterpreterPath如果是绝对路径迁移之后必须改。所以我在准备阶段就有个习惯尽量不在settings里写死解释器路径而是让VS Code自己去探测。VS Code的Python插件会自动找系统PATH里的Python也会找虚拟环境通常都能找到。如果非要用虚拟环境那就把虚拟环境放在项目目录里这样路径相对稳定。另一个要检查的是插件自己的状态文件。如果插件在准备阶段记录了一些绝对路径比如语言服务器的路径迁移后可能也会失效。检查方法就是打开一个Python文件看补全是否正常不正常就去输出面板看Python插件的日志里面会写明它在找什么、找没找到。6. 实测中反复出现的几个问题与对应的解法6.1 报错找不到合适的包到底在说什么离线环境里最常遇到的报错就是这个ERROR: Could not find a version that satisfies the requirement xxx完整的原因链条是这样的pip在--find-links目录里找包它会根据当前Python的版本、平台、ABI去筛选文件名匹配的wheel。如果目录里只有numpy-1.26.4-cp312-cp312-win_amd64.whl而你用的是Python 3.11那pip就会报找不到因为cp312不匹配cp311。排查方法有个小技巧直接列出wheel文件名对照。wheel的命名规则是{包名}-{版本}-{python标记}-{abi标记}-{平台标记}.whl比如numpy-1.26.4-cp311-cp311-win_amd64.whl四个部分分别是包名版本、cp311Python 3.11、cp311ABI、win_amd64平台。你对照目标机器的这三个标记就知道目录里有没有能用的包了。还有一个容易忽视的情况是包的版本号本身有约束。如果你在requirements里写了numpy1.20而目录里最高的才1.19那也会报找不到。离线环境下我建议全部写精确锁定版本这样报错只可能是文件名不匹配排查简单。6.2 PATH污染引发的Python版本错乱装完Python、装完VS Code满以为万事大吉结果命令行里敲python --version蹦出来一个系统自带的旧版本或者pip装包装到了另外的Python里。这是PATH的问题。Windows下PATH是按顺序找的如果系统里本来就有别的Python比如从某个软件附带的它的路径在前面就会先被找到。排查命令是where python where pip这个命令会列出所有叫python的程序路径第一个就是实际被调用的那个。如果第一个不是你期望的就要去调PATH的顺序。VS Code里也有类似的问题。Python插件会探测到多个解释器如果你选错了装包的时候就会装到别的环境。这个在状态栏能看到点左下角的解释器名字可以切换。我吃过一次亏装了半天的包结果解释器选到了另一个Python上一直报模块找不到查了半天才发现是选错了。提示如果目标机器上不可避免有多个Python建议用虚拟环境隔离。虚拟环境用python -m venv venv创建创建后激活所有包都装到这个环境里。虚拟环境的好处是它自带一个pyvenv.cfg记录基础解释器位置迁移的时候整个目录拷过去改一下cfg里的路径就能用。6.3 VS Code扩展装上了但不生效插件装上了但功能没反应这是另一个常见的坑。原因通常是插件之间的依赖没满足或者插件的二进制文件没准备好。具体表现有几种。一种是Python文件的补全不工作光标停在那里转圈这是Pylance的问题。排查方法是看VS Code底部的输出面板选Python Language Server里面会显示它在加载什么、有没有报错。最常见的原因是它想下载某个组件但下不了这时候要么手动把组件补上要么在设置里关掉相关功能。另一种是Jupyter插件找到了Python但找不到内核。这个是因为Jupyter需要注册内核而内核注册依赖于Python环境。离线解决方案是在准备阶段就跑一次python -m ipykernel install --user --name offline-env把内核信息写进去然后把这个内核的配置文件也打包带走。还有一种是插件版本和VS Code版本不匹配报扩展与当前版本不兼容。这个只能换插件版本去市场页面的历史版本里找一个满足engines.vscode要求的。我一般会在准备阶段把所有插件的版本记录一次出一个对照表后面哪天要重建环境就照着这个表来。6.4 磁盘空间和打包体积的平衡离线包越装越大是个现实问题。Python本体百来兆VS Code几百兆插件几百兆再加上一堆numpy、pandas这种带二进制的大包整个包几个G很正常。如果目标机器空间紧张就得做减法。减法的思路有几个。第一只装必需的插件Pylance和Jupyter这种大块头如果不必要就不装语法高亮用Python插件自带的简易功能也能凑合。第二依赖包按需裁剪比如pandas可能只用它的DataFrame那就准备这个就够不用把整个数据科学生态都带上。第三清理缓存pip下载目录里的.cache、VS Code的CachedData这些都可以删掉能省不少。我自己的经验是一个合理的Python开发离线包Python VS Code 核心插件 10个常用库大概在1.5G到2G之间再压缩一下能到800M左右。用7z的最大压缩比打包比zip能小不少这也是我的习惯之一。6.5 版本回退和更新时的注意事项离线环境还有个麻烦是更新。有网的时候更新点一下就行离线环境要从头走一遍准备流程。我的应对策略是保留上一个版本的完整包不要覆盖新建一个带日期或版本号命名的目录。这样新版本出问题的时候能快速回到旧版本。更新的时候有个顺序建议先在测试机上验证新的离线包没问题再往生产环境推。因为离线环境没法在线装补丁一旦推错回退成本很高。我自己维护过的一个环境更新了Python的一个小版本之后有个库因为ABI变化跑不起来还好保留了旧包几分钟就切回去了。还有一点准备新版本包的时候尽量让新旧版本的目录结构一致脚本能通用这样切换的时候只需改一个版本号变量不用重写脚本。这个习惯让我后来的多次升级都很顺基本就是改个参数、重新跑一遍脚本的事。7. 我这些年攒下来的几条实操心得前面把整个流程拆得很细这里说几个从实际操作里抠出来的、文档上一般不会写的点。第一个是关于准备环境的机器选择。准备用的机器最好和目标机器完全一样——同样的操作系统版本、同样的架构、甚至同样的系统补丁级别。我有一次在Windows 10上准备的环境推到Windows Server上结果某个库因为缺一个系统组件跑不起来折腾了很久。后来我就养成了一个习惯准备环境尽量在一个和目标一致的虚拟机里做这样可以随时快照、随时重来也不怕把工作机搞乱。第二个是关于USB介质的选择。离线环境搬运一般靠U盘或移动硬盘这里有个坑是文件系统。如果U盘是FAT32格式单个文件不能超过4G一个大的离线压缩包很容易就超了。所以要么用exFAT或NTFS格式的U盘要么把包切分成多个小文件。我一般会提前把U盘格式化好避免到了现场才发现拷不进去。第三个是关于校验。文件在复制、传输过程中可能损坏尤其是在网络传输或者老旧的U盘上。我习惯在准备端生成一个校验清单用certutil -hashfile 文件名 SHA256到了目标机器上再生成一次对比对不上的重新传。这个步骤看起来多余但真的救过我好几次有一次一个whl文件传输时损坏了装的时候报的解压错误完全不像是文件损坏差点往网络问题上查。第四个是关于文档。每次部署完成后我都会花十分钟写一个部署记录记下这次用的Python版本、VS Code版本、插件版本、遇到的特殊问题、解决办法。这个记录积累下来就成了我自己的一个知识库下次遇到类似环境直接从记录里翻比重新摸索快得多。尤其离线环境很多坑是环境特有的文档的价值比在线环境高得多。最后说一个关于心态的。离线环境部署这事第一次做会觉得处处是坑但做顺了之后会发现它其实比在线环境更可控——因为所有依赖都是你自己准备、自己验证过的不会因为上游更新而突然出问题。我现在反而更倾向于在关键项目上做完整的离线环境包图的就是这种确定性。一次准备多处复用出问题也有据可查这是在线环境给不了的踏实感。
内网离线安装 Python 与 VS Code 开发环境实战指南
1. 为什么要在内网机器上死磕离线安装先说个我自己的真实经历。前年接手一个项目客户的生产车间是纯物理隔离的内网机器装在机柜里网口都是封死的连USB口都做了策略管控。当时需要在这台Windows机器上搭一套Python开发环境用来跑产线上的数据处理脚本和几个自动化测试工具。我一开始想得很天真觉得下个安装包装一装就完事了结果发现完全不是那么回事——Python装完之后要装一堆第三方库pip install全部报连接超时VS Code装完之后一片空白连语法高亮都不给因为Python扩展根本没装上。那次我折腾了整整两天才把一套完整的离线方案跑通。后来这类需求我又碰到过好几次有做嵌入式的朋友要在无外网的工作站上调试C代码有做数据分析的同事要把环境复制到涉密机器上还有要给一批新员工批量部署标准化开发环境的。每次踩的坑都不太一样但核心逻辑是共通的离线环境的本质是把运行时依赖和构建时依赖全部提前打包好然后用一种不依赖网络的方式搬运过去。这里有个很多人一开始就想错的地方。大部分人认为离线安装就是把安装包拷过去装一下但实际上现代开发工具链的依赖是分层的尤其是VS Code加Python这套组合至少涉及四层东西第一层是基础运行时也就是Python解释器本体。第二层是编辑器本体也就是VS Code的程序文件。第三层是编辑器扩展VS Code的Python、Pylance、Jupyter这些插件。第四层是项目依赖包也就是你代码里import的那些第三方库。这四层每一层的离线处理方法都不一样而且层与层之间还有版本匹配的坑。很多教程只讲其中一层结果照着做还是会卡住。我下面会按这四层一条条拆开讲每一层都会给出我自己验证过的操作路径和踩过的具体坑。还有一点要提前说清楚离线环境的准备工作必须在有网的机器上完成而且最好是和目标机器同操作系统、同CPU架构。这一点看起来是废话但我见过太多次有人拿Linux上准备好的包往Windows上搬或者拿x86_64的轮子往ARM板子上装最后全部报错。这个原则贯穿整个流程后面每个环节我都会强调。说说这一套环境最终能达到什么效果。跑通之后目标机器上的VS Code可以正常打开Python文件、有完整的语法高亮和智能补全、能下断点调试、能跑Jupyter Notebook、能正常安装和使用你打包好的第三方库整体体验和有网环境下基本没差别。适合的读者是需要在隔离环境、内网、涉密机器或网络不稳定环境下做Python开发的工程师也包括需要批量部署标准化环境的运维人员。哪怕你之前完全没接触过离线部署跟着走一遍也能搞明白每个环节到底在干什么。2. Python解释器的离线落地从选版本到静默部署2.1 版本选择的门道为什么我建议卡在小版本号上选Python版本这件事有网的时候随便选反正不合适当场再装一个。但离线环境下版本选择要有前瞻性因为后面所有第三方库的兼容性都挂在这个版本上。我的建议是选一个比最新版落后一到两个小版本的稳定版本比如当时最新是3.13那就选3.11或者3.12。原因很实在第三方库对新版Python的适配总是滞后的尤其是那些带C扩展的库比如numpy、pandas、lxml这类它们发布的预编译wheel包就是.whl文件通常只覆盖到某个版本。你要是选了刚发布的最新版很可能在离线源里找不到对应的wheel只能自己编译而编译又要拉一堆构建工具和头文件离线环境下这是灾难。具体到版本号还有个更细的坑Python的小版本号变化会导致wheel不兼容。Python的wheel包命名里带cp311这样的标记意思是CPython 3.11。cp311的包只能装在3.11上装到3.12上会报not a supported wheel on this platform。所以离线环境里定版本的时候最好精确到3.11.x这一级比如锁定3.11.9别到时候目标是3.11.5结果准备了3.11.9的包。至于从哪拿安装包Windows上直接去python.org的下载页面找Windows installer (64-bit)Linux上一般发行版都自带或者从源码编译。这里我不推荐用那些第三方整合包虽然它们号称开箱即用但目录结构经常和标准安装不一样离线迁移的时候会出各种路径问题出了事很难排查。2.2 Windows下的静默安装参数与可选组件拿到安装包比如python-3.11.9-amd64.exe之后有网机器上装一遍当然简单但离线部署到多台机器上时一台台点安装程序太慢而且容易点到不一样的选项。这时候要用静默安装。Python的Windows安装程序支持命令行参数常用的组合是这样python-3.11.9-amd64.exe /quiet InstallAllUsers1 PrependPath1 Include_test0 Include_pip1逐项解释一下。/quiet是静默模式不弹界面。InstallAllUsers1表示给所有用户安装装到C:\Program Files\Python311下面这个很重要因为如果不指定默认是只给当前用户装路径会跑到AppData里多用户环境下其他人用不了。PrependPath1是把Python和Scripts目录加到系统PATH里这样命令行里直接敲python和pip就能用不然每次都要写全路径。Include_test0是跳过测试套件能省几十兆空间离线包本来就金贵能省则省。Include_pip1是确保装上pip虽然通常默认就有但显式写上更保险。有个坑我要单独讲PrependPath1在静默模式下有时候不会立即生效因为环境变量的刷新依赖一个通知机制。装完之后如果发现命令行里敲python还是找不到不是装错了是环境变量没刷新。新开一个命令行窗口通常就好了如果还不行注销重登或者直接去系统属性里看一眼PATH。还有Include_launcher1这个参数也值得加上它会安装py这个启动器。这个启动器在多版本共存的时候特别好用可以写py -3.11精确调用某个版本离线环境下多版本共存是很常见的这个启动器能省不少事。Linux下就简单多了如果是源码包Python-3.11.9.tgz需要先装编译依赖然后./configure --prefix/opt/python3.11 make make install。但离线环境下编译依赖本身也是个大问题编译Python需要gcc、make、zlib-devel、openssl-devel等等一堆东西。所以如果目标机器是Linux我强烈建议优先找现成的二进制包或者用系统的包管理器离线缓存功能比如在能联网的同版本机器上用apt-get install --download-only把deb包下载下来然后拷过去用dpkg -i装这比从源码编译省太多事。2.3 把pip也要离线化本地源目录的建立装完Python之后pip本身是可以用的但它默认去PyPI拉包离线环境下必然失败。解决办法是建一个本地包目录让pip从这个目录装。这里有个非常关键的参数叫--no-index意思是完全不查在线索引只用你指定的本地路径。配合--find-links指定目录命令是这样的pip install --no-index --find-linksD:\offline_pkgs numpy pandas openpyxl--no-index是必须的不加的话pip还是会在超时前尝试访问网络拖慢速度还可能报一堆错。--find-links指向的目录里放的是一堆.whl文件pip会在里面找匹配的包。那这些whl文件怎么来在有网机器上下载。最稳妥的方式是用pip download命令这个命令只下载不安装而且可以指定平台和Python版本pip download --only-binary:all: --platform win_amd64 --python-version 311 --dest D:\offline_pkgs numpy pandas这里--only-binary:all:是强制只下载二进制wheel不下载源码包。为什么强调这个因为源码包.tar.gz到了目标机器上还需要现场编译而编译又需要编译器离线环境下大概率没有。--platform和--python-version是为了下载适配目标机器的包你在Linux上下载给Windows用的包不加这两个参数就会下成Linux的。--dest指定下载目录。注意pip download如果目标包有依赖会把依赖一起下载下来这个特性非常有用。但有时候依赖的依赖会漏掉所以下载完之后最好在目标机器上装一遍缺什么再补什么。我自己的习惯是下载完之后把整个offline_pkgs目录连同Python安装包一起打包放到一个U盘或者移动硬盘里。目录结构大概长这样offline_bundle/ ├── python-3.11.9-amd64.exe ├── offline_pkgs/ │ ├── numpy-1.26.4-cp311-cp311-win_amd64.whl │ ├── pandas-2.2.2-cp311-cp311-win_amd64.whl │ └── ... └── install.bat那个install.bat是我自己写的一键脚本内容就是把静默安装和pip安装串起来执行。这个脚本的具体写法后面讲批处理的时候再展开。3. VS Code本体的搬运便携模式与配置固化3.1 用户安装器还是系统安装器这是个分岔路口VS Code有两个版本的安装器一个是User Installer用户安装器装在用户目录下一个是System Installer系统安装器装在Program Files下。有网环境下随便选但离线场景我强烈推荐用System Installer或者干脆用它的ZIP免安装版。理由是这样的User Installer装到AppData\Local\Programs下面这台机器上换一个用户登录VS Code就没了配置也是每个用户一份。而离线部署往往是给一批机器或者一台机器的多个使用场景用的用户级的安装会带来重复配置的麻烦。System Installer装完之后全机器可用配置放在统一的位置方便我一次性把配置写好然后批量复制。如果你连安装都想免掉那就用ZIP版。VS Code官网提供.zip格式的免安装包解压就能跑不写注册表。这种方式的优势是我可以把整个VS Code目录连同配置一起打包拷到目标机器上解压就完事不需要管理员权限特别适合权限受限的环境。缺点是右键菜单、文件关联这些系统集成功能没有但对于纯写代码来说影响不大。3.2 便携模式怎么开data目录的妙用说到ZIP版就不得不提VS Code的便携模式Portable Mode。这个模式很多天天用VS Code的人都不知道但对离线部署来说是个宝贝。开启方法很简单在VS Code的解压目录里和Code.exe同级的位置新建一个名字叫data的文件夹。VS Code启动的时候检测到这个data目录存在就会把用户数据、扩展、缓存全部放到这个目录里而不是放到AppData下面。这个机制的价值在于所有的环境数据都集中在一个目录树里迁移的时候直接拷整个文件夹就行配置、插件、设置全都跟着走。我在标准化部署的时候就是这么干的在有网机器上开便携模式装好所有需要的插件配好settings.json测好Python解释器路径然后把这个文件夹整体打包。目标机器上解压改一下路径相关的配置就能直接用。配置目录的结构大致是这样VSCode-Portable/ ├── Code.exe ├── data/ │ ├── user-data/ │ │ ├── User/ │ │ │ ├── settings.json │ │ │ └── snippets/ │ │ └── ... │ └── extensions/ │ ├── ms-python.python-2024.x.x/ │ ├── ms-python.vscode-pylance-2024.x.x/ │ └── ...user-data\User\settings.json是用户设置extensions目录就是你装的插件。这个结构清楚了之后后面做迁移和备份都一目了然。3.3 离线安装插件VSIX文件的获取与安装VS Code的插件在正常情况下是从市场Marketplace在线下载的离线环境下市场是打不开的。解决办法是提前把插件下载成.vsix文件然后离线安装。获取vsix文件有两种方式。第一种是在有网的VS Code里找到插件点齿轮图标选Download VSIX它会下载到本地。但这个方法需要插件页面上有这个选项不是所有插件都有。第二种更可靠是从市场网站直接搜插件进到详情页在Version History里找到想要的具体版本点下载。这种方式的好处是我能精确控制版本避免下到最新版结果和目标VS Code版本不兼容。VS Code的插件版本和VS Code本体版本之间是有兼容要求的插件的package.json里有个engines.vscode字段比如^1.80.0意思是需要VS Code 1.80以上。如果你下的插件要求1.85而目标机器上的VS Code是1.80装的时候会提示不兼容。所以在下载插件之前最好先确认目标VS Code的版本要求或者反过来先把VS Code版本定下来再挑兼容的插件版本。安装vsix的命令行方式是这样code --install-extension ms-python.python-2024.6.0.vsixcode命令在装VS Code的时候如果勾选了添加到PATH就会有ZIP版的话在bin目录下有code.cmd。如果命令行调不通也可以在VS Code界面里扩展面板右上角三个点选Install from VSIX然后选文件。Python开发必需的插件我列一下这些是必备的插件名称扩展ID作用Pythonms-python.python核心支持调试、运行、环境管理Pylancems-python.vscode-pylance智能补全、类型检查Jupyterms-toolsai.jupyterNotebook支持Black Formatterms-python.black-formatter代码格式化Pylance这个插件要注意它体积不小而且依赖Python扩展。安装顺序最好先装Python再装Pylance不然可能会有依赖警告。Jupyter插件也是个大块头如果不用Notebook可以不装能省不少空间。提示插件装完之后VS Code会在extensions目录下建对应文件夹每个文件夹里会有一个.obsolete文件或者.extension标记。如果你想确认插件是否真的装上了看这个目录比看界面更直观。3.4 插件依赖的二进制文件一个容易被忽略的坑这里要讲一个很多人会踩的坑。有些VS Code插件内部会去下载额外的二进制文件在线的时候自动下离线的时候就卡住。最典型的是Pylance它本身是个语言服务器插件包里带了一部分的二进制但某些版本会尝试下载额外的组件。Jupyter插件的一些内核管理功能也会去下东西。规避方法是在准备阶段把插件在联网环境下完整激活一遍——打开一个Python文件让Pylance完成一次索引打开一个Notebook让Jupyter把内核检测跑一遍。这样触发它把该下的东西都下到插件目录里。然后你再打包这些下载好的文件就会跟着走。我自己测试的时候就吃过这个亏插件装上了但Python文件的补全一直转圈查了半天才发现是语言服务器的一个组件没下下来。4. 项目依赖包的完整打包从离线源到跨平台兼容4.1 依赖清单怎么生成requirements.txt的正确用法前面讲了单个包的下载但实际项目里依赖是成套的而且有版本约束。这时候要用requirements.txt来管理。生成依赖清单的标准做法是在项目环境里跑pip freeze requirements.txt但这个命令有个问题它会把环境里所有包都列进去包括那些间接依赖和跟项目无关的。更精准的方式是只导出项目直接依赖或者用pipreqs这种工具扫描代码里的import语句来生成。有了清单之后下载命令变成pip download --only-binary:all: --platform win_amd64 --python-version 311 -r requirements.txt --dest D:\offline_pkgs批量下载的好处是依赖关系会被pip自动解析不会漏包。但这里有个隐蔽的坑如果某个包只有源码包没有wheel包加了--only-binary:all:会直接报错而不是跳过。这时候要单独处理这个包要么去掉这个参数让它下源码包前提是目标机器能编译要么找替代的纯Python实现。我遇到过好几次这种情况比如某个小众库只发.tar.gz。处理办法是提前在目标环境探测一遍把这类包列出来单独准备。还有一种情况是某些包虽然发了wheel但只发了特定平台的比如只有macosx的轮子没有win_amd64的这种在Windows目标机上就得找源码编译。4.2 跨平台下载的技巧--platform和--abi的配合跨平台准备包这件事说起来简单做起来容易错。因为pip download默认是按当前机器的环境来下你在Linux上跑它就下Linux的包。要下给别用的必须把目标参数显式写全。完整的参数组合是这样pip download \ --only-binary:all: \ --platform win_amd64 \ --python-version 311 \ --implementation cp \ --abi cp311 \ -r requirements.txt \ --dest D:\offline_pkgs--platform指定目标系统的架构标识常见的有win_amd64、manylinux2014_x86_64、macosx_11_0_arm64这些。--python-version是Python版本写311就是3.11。--implementation是解释器实现一般都是cpCPython。--abi是应用二进制接口通常和Python版本对应cp311。这套参数要全部写对少一个都可能下错包。--platform和--abi要匹配比如你写--platform win_amd64但--abi写成了cp311m那个m是pymalloc标记Python 3.8之后就没这个了就会报找不到合适的包。还有一个特殊的架构标识叫any专门给纯Python的包用。有些包比如requests是纯Python写的它的wheel名字里带py3-none-any意思是任何Python 3、任何平台都能用。这种包不用管--platformpip会优先选它。4.3 版本锁定的价值一次准备多次复用离线环境准备最怕的就是这次能用下次不能用。避免这个问题的方法是把版本完全锁死。pip freeze导出的清单其实是带版本号的比如numpy1.26.4。但pip download的时候如果不加约束它可能会去下一堆相关的包的最新版。为了保证一致性可以把下载和安装都基于同一个requirements.txt并且在里面把所有包都写成精确版本。更狠一点的做法是用pip-compile来自pip-tools来生成一个完全锁定版本的清单包括所有间接依赖的版本都被锁死。这样在任何机器上重现的环境都是一模一样的离线环境下这一点特别重要因为你没法在线装个新版本来试试行不行。我自己的习惯是每次给离线环境准备包的时候都记一个环境快照包含这些信息Python的精确版本号操作系统和架构所有包的精确版本下载时的完整命令这个快照存一份在项目的docs目录里下次要给别人复制环境或者过了几个月要重建环境照着快照来就行不会出现当时能跑现在跑不了的尴尬。5. 一键化部署脚本让重复劳动自动化5.1 批处理脚本的组织结构前面每一步都讲完了但如果每次部署都手动敲一遍命令那太折磨人了。我后来把这些步骤全部串成脚本一次写好到处能用。Windows下用.bat批处理Linux下用.sh。先说Windows的。脚本的整体思路是先检查Python是否已安装、版本对不对没装就静默安装然后设置环境变量再装pip包最后装VS Code和插件。写批处理有几个坑要避开。第一是管理员权限装System级别的Python和写PATH都需要管理员权限批处理开头要加权限检测echo off net session nul 21 if %errorlevel% neq 0 ( echo 请以管理员身份运行此脚本 pause exit /b 1 )这段net session是个经典技巧它能检测当前是不是有管理员权限因为普通用户跑这个命令会报错。第二是路径里有空格的问题。C:\Program Files这种路径在批处理里如果不加引号会被截断。所有涉及路径的地方都要养成加引号的习惯。第三是错误处理脚本里每执行一步都要检查%errorlevel%失败了就报错停下别让脚本一路跑到底最后报一堆无关错误。5.2 安装脚本的核心流程一个完整的安装脚本核心流程大概是这样组织的echo off setlocal enabledelayedexpansion set PYTHON_VERSION3.11.9 set PYTHON_EXEpython-%PYTHON_VERSION%-amd64.exe set OFFLINE_PKGS%~dp0offline_pkgs set VSCode_DIR%~dp0VSCode-Portable echo [1/4] 检查Python环境... python --version 2nul | findstr %PYTHON_VERSION% nul if %errorlevel% neq 0 ( echo 未检测到目标版本开始安装... %PYTHON_EXE% /quiet InstallAllUsers1 PrependPath1 Include_test0 Include_launcher1 if !errorlevel! neq 0 ( echo Python安装失败 exit /b 1 ) ) echo [2/4] 安装离线依赖包... python -m pip install --no-index --find-links%OFFLINE_PKGS% -r %~dp0requirements.txt if !errorlevel! neq 0 ( echo 依赖包安装失败请检查offline_pkgs目录 exit /b 1 ) echo [3/4] 部署VS Code... xcopy /E /I /Y %VSCode_DIR% %LOCALAPPDATA%\VSCode-Portable echo [4/4] 安装VS Code插件... for %%f in (%~dp0vsix\*.vsix) do ( %LOCALAPPDATA%\VSCode-Portable\bin\code.cmd --install-extension %%f ) echo 部署完成 endlocal这个脚本里有几个细节值得说。%~dp0是批处理的内置变量表示脚本自身所在的目录d是drivep是path用它可以保证脚本不管在哪个目录下执行都能找到同目录下的资源。setlocal enabledelayedexpansion开启延迟变量扩展这样在if块里才能用!errorlevel!而不是%errorlevel%这是批处理里的一个经典陷阱不开启的话if块里的错误码永远是进入块之前的值。findstr那段是版本检测如果已经装了目标版本就跳过安装能避免重复装。xcopy /E /I /Y是复制目录/E包含空目录/I是如果目标是目录就当作目录处理/Y是覆盖不提示。5.3 配置文件的路径修正最容易忘的一步脚本跑完环境装好了但这时候VS Code里的Python解释器路径大概率还是错的因为settings.json里如果写死了绝对路径换台机器就失效了。settings.json里和Python相关的配置主要是这几项{ python.defaultInterpreterPath: C:\\Program Files\\Python311\\python.exe, python.analysis.typeCheckingMode: basic, python.formatting.provider: black, editor.formatOnSave: true, files.autoSave: afterDelay }python.defaultInterpreterPath如果是绝对路径迁移之后必须改。所以我在准备阶段就有个习惯尽量不在settings里写死解释器路径而是让VS Code自己去探测。VS Code的Python插件会自动找系统PATH里的Python也会找虚拟环境通常都能找到。如果非要用虚拟环境那就把虚拟环境放在项目目录里这样路径相对稳定。另一个要检查的是插件自己的状态文件。如果插件在准备阶段记录了一些绝对路径比如语言服务器的路径迁移后可能也会失效。检查方法就是打开一个Python文件看补全是否正常不正常就去输出面板看Python插件的日志里面会写明它在找什么、找没找到。6. 实测中反复出现的几个问题与对应的解法6.1 报错找不到合适的包到底在说什么离线环境里最常遇到的报错就是这个ERROR: Could not find a version that satisfies the requirement xxx完整的原因链条是这样的pip在--find-links目录里找包它会根据当前Python的版本、平台、ABI去筛选文件名匹配的wheel。如果目录里只有numpy-1.26.4-cp312-cp312-win_amd64.whl而你用的是Python 3.11那pip就会报找不到因为cp312不匹配cp311。排查方法有个小技巧直接列出wheel文件名对照。wheel的命名规则是{包名}-{版本}-{python标记}-{abi标记}-{平台标记}.whl比如numpy-1.26.4-cp311-cp311-win_amd64.whl四个部分分别是包名版本、cp311Python 3.11、cp311ABI、win_amd64平台。你对照目标机器的这三个标记就知道目录里有没有能用的包了。还有一个容易忽视的情况是包的版本号本身有约束。如果你在requirements里写了numpy1.20而目录里最高的才1.19那也会报找不到。离线环境下我建议全部写精确锁定版本这样报错只可能是文件名不匹配排查简单。6.2 PATH污染引发的Python版本错乱装完Python、装完VS Code满以为万事大吉结果命令行里敲python --version蹦出来一个系统自带的旧版本或者pip装包装到了另外的Python里。这是PATH的问题。Windows下PATH是按顺序找的如果系统里本来就有别的Python比如从某个软件附带的它的路径在前面就会先被找到。排查命令是where python where pip这个命令会列出所有叫python的程序路径第一个就是实际被调用的那个。如果第一个不是你期望的就要去调PATH的顺序。VS Code里也有类似的问题。Python插件会探测到多个解释器如果你选错了装包的时候就会装到别的环境。这个在状态栏能看到点左下角的解释器名字可以切换。我吃过一次亏装了半天的包结果解释器选到了另一个Python上一直报模块找不到查了半天才发现是选错了。提示如果目标机器上不可避免有多个Python建议用虚拟环境隔离。虚拟环境用python -m venv venv创建创建后激活所有包都装到这个环境里。虚拟环境的好处是它自带一个pyvenv.cfg记录基础解释器位置迁移的时候整个目录拷过去改一下cfg里的路径就能用。6.3 VS Code扩展装上了但不生效插件装上了但功能没反应这是另一个常见的坑。原因通常是插件之间的依赖没满足或者插件的二进制文件没准备好。具体表现有几种。一种是Python文件的补全不工作光标停在那里转圈这是Pylance的问题。排查方法是看VS Code底部的输出面板选Python Language Server里面会显示它在加载什么、有没有报错。最常见的原因是它想下载某个组件但下不了这时候要么手动把组件补上要么在设置里关掉相关功能。另一种是Jupyter插件找到了Python但找不到内核。这个是因为Jupyter需要注册内核而内核注册依赖于Python环境。离线解决方案是在准备阶段就跑一次python -m ipykernel install --user --name offline-env把内核信息写进去然后把这个内核的配置文件也打包带走。还有一种是插件版本和VS Code版本不匹配报扩展与当前版本不兼容。这个只能换插件版本去市场页面的历史版本里找一个满足engines.vscode要求的。我一般会在准备阶段把所有插件的版本记录一次出一个对照表后面哪天要重建环境就照着这个表来。6.4 磁盘空间和打包体积的平衡离线包越装越大是个现实问题。Python本体百来兆VS Code几百兆插件几百兆再加上一堆numpy、pandas这种带二进制的大包整个包几个G很正常。如果目标机器空间紧张就得做减法。减法的思路有几个。第一只装必需的插件Pylance和Jupyter这种大块头如果不必要就不装语法高亮用Python插件自带的简易功能也能凑合。第二依赖包按需裁剪比如pandas可能只用它的DataFrame那就准备这个就够不用把整个数据科学生态都带上。第三清理缓存pip下载目录里的.cache、VS Code的CachedData这些都可以删掉能省不少。我自己的经验是一个合理的Python开发离线包Python VS Code 核心插件 10个常用库大概在1.5G到2G之间再压缩一下能到800M左右。用7z的最大压缩比打包比zip能小不少这也是我的习惯之一。6.5 版本回退和更新时的注意事项离线环境还有个麻烦是更新。有网的时候更新点一下就行离线环境要从头走一遍准备流程。我的应对策略是保留上一个版本的完整包不要覆盖新建一个带日期或版本号命名的目录。这样新版本出问题的时候能快速回到旧版本。更新的时候有个顺序建议先在测试机上验证新的离线包没问题再往生产环境推。因为离线环境没法在线装补丁一旦推错回退成本很高。我自己维护过的一个环境更新了Python的一个小版本之后有个库因为ABI变化跑不起来还好保留了旧包几分钟就切回去了。还有一点准备新版本包的时候尽量让新旧版本的目录结构一致脚本能通用这样切换的时候只需改一个版本号变量不用重写脚本。这个习惯让我后来的多次升级都很顺基本就是改个参数、重新跑一遍脚本的事。7. 我这些年攒下来的几条实操心得前面把整个流程拆得很细这里说几个从实际操作里抠出来的、文档上一般不会写的点。第一个是关于准备环境的机器选择。准备用的机器最好和目标机器完全一样——同样的操作系统版本、同样的架构、甚至同样的系统补丁级别。我有一次在Windows 10上准备的环境推到Windows Server上结果某个库因为缺一个系统组件跑不起来折腾了很久。后来我就养成了一个习惯准备环境尽量在一个和目标一致的虚拟机里做这样可以随时快照、随时重来也不怕把工作机搞乱。第二个是关于USB介质的选择。离线环境搬运一般靠U盘或移动硬盘这里有个坑是文件系统。如果U盘是FAT32格式单个文件不能超过4G一个大的离线压缩包很容易就超了。所以要么用exFAT或NTFS格式的U盘要么把包切分成多个小文件。我一般会提前把U盘格式化好避免到了现场才发现拷不进去。第三个是关于校验。文件在复制、传输过程中可能损坏尤其是在网络传输或者老旧的U盘上。我习惯在准备端生成一个校验清单用certutil -hashfile 文件名 SHA256到了目标机器上再生成一次对比对不上的重新传。这个步骤看起来多余但真的救过我好几次有一次一个whl文件传输时损坏了装的时候报的解压错误完全不像是文件损坏差点往网络问题上查。第四个是关于文档。每次部署完成后我都会花十分钟写一个部署记录记下这次用的Python版本、VS Code版本、插件版本、遇到的特殊问题、解决办法。这个记录积累下来就成了我自己的一个知识库下次遇到类似环境直接从记录里翻比重新摸索快得多。尤其离线环境很多坑是环境特有的文档的价值比在线环境高得多。最后说一个关于心态的。离线环境部署这事第一次做会觉得处处是坑但做顺了之后会发现它其实比在线环境更可控——因为所有依赖都是你自己准备、自己验证过的不会因为上游更新而突然出问题。我现在反而更倾向于在关键项目上做完整的离线环境包图的就是这种确定性。一次准备多处复用出问题也有据可查这是在线环境给不了的踏实感。
