统信UOS信创整机Python开发环境搭建：VS Code与venv实践

1. 在统信UOS上搭Python，我为什么不推荐直接用系统自带的解释器

信创环境下拿到一台浪潮整机，预装统信UOS，第一反应往往是打开终端敲python3 --version，看到版本号能出来，就觉得"环境有了"。我最初也是这么想的，直到一个项目在本地跑得好好的，拷到另一台同型号机器上直接报依赖冲突，才发现问题不在代码，而在我把开发环境建在了系统 Python 上面。

这个标题里其实藏着三件事：一台国产整机、一套统信UOS桌面系统、一个 Python 开发环境的搭建过程。三者叠在一起，跟你在常见发行版上装环境的手感完全不一样——架构可能是 ARM，包管理是 apt 但源里的东西未必齐，安全策略还会拦你一手，输入法、字体、扩展市场各有各的坑。这篇就把我从零到能正常调试、能打包迁移的完整过程摊开讲，适合刚接手信创开发机、或者准备把主力开发环境迁到 UOS 上的人。

1.1 系统 Python 到底是"基础设施"还是"能用的工具"

统信UOS 基于 Debian 系，系统里一定存在一个python3，因为桌面环境的一部分组件就是用它写的。这意味着两件事：一是它确实能用，二是它不该被你随便动。

我见过有人上来就sudo pip3 install一堆库，装完当时能跑，系统更新一次桌面组件崩了，查半天查不出来。原因很简单：系统 Python 的site-packages是共享的，你装进去的包可能会覆盖系统组件依赖的版本。所以第一条铁律是——系统自带的 Python 只当"引导程序"用，不往上装业务依赖。

那它能不能删？别删。你不需要它的时候不管它就行，UOS 的部分系统工具靠它活着。

1.2 三条路线：改系统 Python、装多版本、还是干脆全放虚拟环境

在动手之前先把路线定下来，比装到一半再返工省事得多。我整理了一张对照表，这是我实际都试过之后的结论。

路线	做法	优点	实际代价
直接用系统 Python	在/usr/bin/python3上装包	零配置，敲命令就能跑	污染系统环境，更新后容易出玄学问题
自己编译/装多版本 Python	源码编译或找第三方源装 3.11、3.12	版本自由，系统 Python 不受影响	编译耗时长，ARM 平台更容易缺依赖
每个项目一个 venv	基于系统 Python 建虚拟环境	隔离干净，删目录即卸载，迁移方便	每开一个新项目要激活一次

我的选择是第三条，而且不折腾多版本。原因很现实：信创机器的 CPU 性能普遍不算强，源码编译 Python 一次要十几分钟甚至半小时，还要装一堆-dev包；而 venv 建一个只要一两秒。除非某个库硬性要求 3.11 以上，否则直接用系统自带的 3.10/3.11 建 venv 完全够用。

提示：如果确实需要多版本共存，建议用pyenv的"预编译安装"或者发行版源里的python3.x包，不要一上来就源码编译，ARM 平台编译报错的排查成本比你想的高。

1.3 先想清楚代码最终跑在哪台机器上

这一步很多人跳过，然后在部署时被坑。开发机是 ARM 架构，服务器是 x86，或者反过来，那么任何一个带 C 扩展的库（numpy、pandas、cryptography、lxml）在两边装的 wheel 包都不是同一个。本地pip install顺利，打包到服务器上就找不到匹配的 wheel，只能回退到源码编译，然后在服务器上缺编译器。

所以我的习惯是：先确认目标运行环境的架构和 Python 版本，再决定开发机上装什么。这台浪潮机器如果是 ARM 或国产指令集，而线上是 x86，那开发机上那些带二进制扩展的依赖就得格外小心，必要时用容器对齐环境，而不是指望 pip 自动搞定。

先把这一层想清楚，后面装 VS Code、配解释器才有的放矢。

2. 装 VS Code 之前，先把这台机器的底摸清楚

我在 UOS 上装开发工具翻过几次车，回头复盘，问题几乎都出在"没先看机器是什么"。国产整机的 CPU 五花八门，包管理器虽然都是 apt，但软件源里有没有你要的包、包是什么架构，完全是另一回事。开工前花三分钟做环境盘点，能省掉两小时排查。

2.1uname -m的结果直接决定你去哪找安装包

打开终端，第一条命令就是看架构：

uname -m cat /etc/os-release

可能出现的几种结果，对应的处理方式完全不同：

• x86_64：最省事，VS Code 官方 deb 包直接装，Python 生态的预编译 wheel 也最全。
• aarch64：VS Code 有官方 ARM64 版本，numpy 等主流库也有 ARM 的 wheel，整体顺畅，个别小众库需要自己编译。
• loongarch64或其它国产指令集：官方构建基本没有，需要找社区构建版本或者用系统应用商店里的替代编辑器，同时 Python 侧很多 wheel 需要源码编译，必须提前装好build-essential和对应的-dev包。

/etc/os-release里能看出系统的具体版本号，这一点很关键——不同版本的 UOS，应用商店里能搜到的东西不一样，源配置格式也可能有差异。我当时就是按旧版本的经验去配源，结果文件路径都变了，白折腾一轮。

顺便看一眼磁盘和内存，Python 项目加上虚拟环境、扩展缓存，home 分区太紧会很难受：

df -h /home free -h

2.2 开发者模式与 sudo 权限：不注意就卡在第一步

信创整机出厂时通常是普通用户权限，装软件要么走应用商店，要么先在控制中心的"通用"里打开"开发者模式"。这一步不做，你在终端里sudo会各种不顺手，装 deb 包也容易被安全中心拦下来。

我的操作顺序是这样的：

1. 控制中心 → 通用 → 开发者选项 → 打开开发者模式（需要同意相关条款，部分版本要求登录账号）。
2. 打开终端，sudo -v验证一下 sudo 是否可用。
3. 装完 deb 包如果提示"来源不可信"或被安全中心拦截，去安全中心把该安装包加入信任或临时放行，这是正常流程，不是系统坏了。

注意：开发者模式和 sudo 权限是本地开发环境的常规操作，不要为了图省事长期用 root 登录图形界面，权限混乱之后出问题的排查成本极高。

2.3 源、依赖和基础工具链，一次性补齐

在装编辑器之前，我习惯先把命令行侧的东西一次装齐。这样后面任何一步卡住，都排除了"是不是少个包"的干扰项。

sudo apt update sudo apt install -y \ python3 python3-pip python3-venv python3-dev \ build-essential git curl wget ca-certificates \ fonts-noto-cjk

几个包的作用我心里有数，装的时候就不盲目：

• python3-venv：没有它，python3 -m venv会直接报错，这是新手最常踩的第一个坑。
• python3-dev：提供 Python 头文件，源码编译 C 扩展时必须。
• build-essential：gcc、make等，ARM 环境下大概率会用上。
• fonts-noto-cjk：中文字体，终端和编辑器里的中文显示靠它。

如果apt update特别慢，说明源指向的地址不通畅或者速度差。UOS 一般自带国内源，但如果你装过其它系统的源配置，建议用系统默认的，别乱混。

这里有个我自己的经验：在信创机器上，能装 apt 包的绝不去官网下 tar.gz。发行版维护者已经帮你处理了架构适配和依赖关系，自己解压的版本在 ARM 上十有八九会缺动态库，报错信息还特别难看懂。

3. 三种安装 VS Code 的方式，我为什么最后选了 deb 包

装编辑器本身不难，难的是"哪种方式在你手里这台机器上真的能用"。我在三台不同配置的浪潮整机上分别试了应用商店、deb 包、解压版三种路径，结论很明确，但过程值得说说。

3.1 deb 包安装：最稳，但依赖要补

从官网下载对应架构的 deb 包，x86_64 和 arm64 都有。装的时候我不用dpkg -i一把梭，而是两步走：

sudo dpkg -i ./code_x.x.x_amd64.deb sudo apt -f install -y

第一句装包，如果缺依赖会报错但不会中断；第二句让 apt 自动把缺的依赖补齐。这个组合比直接apt install ./xxx.deb更可控，出问题能看到具体缺哪个库。

装完确认一下：

code --version which code

如果code命令找不到，多半是没进 PATH，用绝对路径/usr/share/code/code也能启动，或者重启一次终端会话让它生效。

3.2 应用商店与解压版：适用场景不一样

UOS 的应用商店里能搜到 VS Code 或者它的衍生版本，优点是点点鼠标就装完，权限、来源、依赖全有人管，如果你的机器是国产指令集架构，这可能是唯一能正常跑起来的路径。缺点是版本更新滞后，扩展市场有时被替换或裁剪，我遇到过商店版本里连中文语言包都搜不到的情况。

解压版（tar.gz）是另一条路：不用 root 权限，扔到家目录里就能跑，适合没有开发者模式、或者你想同时装多个版本对比的场景。代价是你得自己处理桌面图标、文件关联、以及各种动态库依赖。在 ARM 机器上，我见过解压后启动直接报缺libgbm的，还得回头 apt 补。

三条路的取舍，我个人的排序是：

场景	推荐方式	理由
x86_64 / arm64，有 sudo 权限	官方 deb 包	版本新，扩展市场完整，升级方便
国产指令集架构	应用商店	大概率是唯一能用的，省事
无 root 权限、临时试用	tar.gz 解压	不动系统，随手删

3.3 首次启动必做的四件事

第一启动界面出来后，我会按固定顺序做四件事，缺一件后面都会别扭。

一是关掉自动更新。信创环境通常网络策略比较紧，自动更新会反复弹窗、卡顿，甚至因为连不上而一直转圈。在设置里把update.mode改成none，需要升级时我手动下包。

二是确认扩展面板能打开。如果侧边栏的扩展图标点开一直转圈，先别急着怀疑网络，往下看第 6 节，我把排查顺序写全了。

三是配置终端。VS Code 内置终端默认调用的 shell 在 UOS 上通常是 bash，这没问题，但中文字体和输入法要单独处理，见下一节。

四是把常用的工作目录加到工作区。别小看这个，后面配解释器、配settings.json都是围绕工作区来的，一开始就把目录结构定好，省得改来改去。

4. 中文环境才是真正的分水岭：语言包、输入法、字体

到这一步，英文界面基本能用了，但作为一个每天要在这上面写几小时代码的人，中文环境不顺手是真的难受。这三块我每块都踩过坑，逐个说。

4.1 界面中文化与设置顺序

中文语言包在扩展市场里搜 "Chinese" 就能找到官方那个，装完右下角会提示重启。装不上、或者商店里搜不到的时候，就走到离线安装那条路——在能上网的机器上从市场网页下载.vsix文件，拷过来后：

code --install-extension ./ms-ceintl.vscode-language-pack-zh-hans-*.vsix

这里有个我踩过的顺序问题：先装语言包再装 Python 扩展。有一回我先装了 Python 扩展，它自动拉了一串依赖扩展，其中某个版本和系统 GLIBC 不兼容，导致整个编辑器启动就闪退，最后只能清掉~/.vscode/extensions重来。所以我的习惯是：每装两三个扩展就重启一次，确认没崩再继续。

4.2 输入法在编辑器里打不出中文，根因在环境变量

这是 UOS 上最典型的坑：终端里能用输入法打中文，VS Code 的编辑器里就是打不出来，或者候选框飘到屏幕左上角。根因是 VS Code 是 Electron 应用，走的是 GTK 的输入法模块，而系统默认的输入法框架没被它继承到。

处理方式是在 shell 配置里显式声明输入法模块：

# 加到 ~/.bashrc 或 ~/.profile export GTK_IM_MODULE=fcitx export QT_IM_MODULE=fcitx export XMODIFIERS=@im=fcitx

改完之后要完全退出 VS Code 再重新启动，从终端里code启动，让它继承这些变量；直接点桌面图标启动有时读不到。如果候选框位置还是不对，把窗口从最大化切回普通大小再切回来，通常能复位。

提示：不同版本的 UOS 用的输入法框架可能不同，先看看系统里装的是 fcitx 还是别的，变量名要跟实际框架对上，写错了反而会让输入完全失效。

4.3 字体、终端外观和几个提升舒适度的小设置

中文字体在代码编辑器里最怕两件事：一是等宽对不齐，二是中英文行高不一致显得很跳。我的做法是配一个中英文混合字体族：

{ "editor.fontFamily": "'Noto Sans Mono CJK SC', 'DejaVu Sans Mono', 'Consolas', monospace", "editor.fontSize": 14, "editor.lineHeight": 1.6, "terminal.integrated.fontFamily": "'Noto Sans Mono CJK SC', monospace" }

lineHeight调到 1.5 到 1.7 之间，中文注释的可读性提升非常明显，尤其在这类分辨率不高的国产显示器上。

另外几个我必改的设置：files.autoSave设成onFocusChange，避免误关文件丢内容；editor.renderWhitespace设成boundary，方便发现混进来的全角空格——中文输入法下误打全角空格是个高频事故，Python 直接报语法错误，还很难看出来。

5. 解释器绑定和虚拟环境：把环境这件事一次性做对

前面都是铺垫，这里才是核心。VS Code 本身只是个编辑器，真正干活的是它背后调用的那个 Python 解释器。它调到哪个解释器，就决定了你的代码跑在什么环境里，这一点千万不能含糊。

5.1 先建 venv，再让编辑器去找它

我不用编辑器自带的"创建环境"按钮，而是自己在终端里建，因为过程可见、出问题好排查：

cd ~/projects/demo python3 -m venv .venv source .venv/bin/activate python -m pip install -U pip setuptools wheel

最后那句升级 pip 是我雷打不动要做的。系统源里的 pip 版本往往比较旧，旧 pip 在解析复杂依赖树时会给出令人费解的错误，或者下载不到某些新格式的 wheel，升级之后很多"玄学问题"直接消失。

建完之后回到 VS Code，Ctrl+Shift+P输入Python: Select Interpreter，选择.venv/bin/python。选完之后，编辑器底部的状态栏会显示当前解释器路径，养成看一眼状态栏的习惯，我至少有三次因为忘了切解释器，在系统环境里装了一堆包还没反应过来。

5.2 用 settings.json 把配置固化进仓库

靠鼠标点选是临时状态，换台机器就得重来一遍。真正省事的做法是在项目根目录建.vscode/settings.json，写进版本控制：

{ "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", "python.terminal.activateEnvironment": true, "python.analysis.typeCheckingMode": "basic", "python.analysis.autoImportCompletions": true, "files.watcherExclude": { "**/.venv/**": true, "**/__pycache__/**": true, "**/.git/objects/**": true } }

几个字段的作用说清楚：

• defaultInterpreterPath：新克隆仓库时自动指向项目内的 venv，队友不用手动选。
• activateEnvironment：在内置终端里执行 Python 命令时自动激活虚拟环境，避免"终端里装的包和编辑器用的解释器对不上"这种经典混乱。
• typeCheckingMode：开basic就能在写代码时提示明显的类型问题，又不至于被strict的意见淹死。
• watcherExclude：把 venv 和__pycache__排除出文件监视，这在国产整机上体感提升很大，否则打开大项目时编辑器会持续卡顿。

注意：settings.json里如果写死了绝对路径，换机器就废了。一律用${workspaceFolder}变量，这是能跨机器复用的关键。

5.3 launch.json：让 F5 真的能跑起来

调试配置我一般只留一个通用模板，够用且不啰嗦：

{ "version": "0.2.0", "configurations": [ { "name": "Python: 当前文件", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal", "justMyCode": true, "env": { "PYTHONPATH": "${workspaceFolder}" } } ] }

console用integratedTerminal而不是internalConsole，是因为涉及input()或者需要看彩色输出的场景，内部控制台经常会显示异常或没法输入。PYTHONPATH指向工作区根目录，能解决"模块导入报 ModuleNotFoundError"的一大半问题——尤其在你把代码放在子目录里的时候。

如果用的是较老版本的 Python 扩展，type字段可能还是python而不是debugpy。这个不用纠结，看编辑器提示改就行，两个名字对应的是不同扩展版本。

6. 六个坑：我在UOS上装环境时真实卡过的地方

这一节是全篇我最想写的部分。前面那些步骤，看文档都能查到；下面这些是我真正耗掉时间的地方，按我当时的排查顺序列出来，你遇到类似现象可以照着走。

6.1 pip 装包卡住或者超时

现象是pip install卡在Downloading不动，几分钟后报Read timed out。这不是网络坏了，是默认源太远。解决办法是配置国内镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.timeout 60

配好之后可以用pip config list确认。要注意的是，这个配置写在用户级配置文件里，对 venv 同样生效；如果你在多个环境间切换时发现源不一致，去~/.config/pip/pip.conf看看。

6.2sudo pip埋下的雷

我早期图省事用过sudo pip3 install，结果是包被装进系统目录，普通用户跑脚本时导入的却是另一份，版本对不上，报错信息指向一个根本不存在的符号。清理起来很麻烦，因为系统包里混进了不该有的东西，还不敢乱删。

正确的处理只有两条：用虚拟环境，或者用pip install --user装到用户目录。出了问题想回退时，我一般这么做：

python3 -m pip list --user python3 -m pip uninstall 包名

实在混乱了，就把用户目录下的~/.local/lib/python3.x/site-packages看一眼，找出明显不该在那里的包手动清理，别整个删目录。

6.3 扩展市场打不开：按这个顺序排查

扩展面板一直转圈，我从外到内排查了四层：

1. 先确认浏览器能不能打开普通网站，排除整体网络不通。
2. 看代理设置是否被误配：设置里搜http.proxy，如果有残留值就清空。
3. 检查证书：企业网络环境下证书链不全会导致 HTTPS 请求失败，可以临时设置http.systemCertificates或http.proxyStrictSSL试一下。
4. 都不行就走离线路线——在能上网的机器上下载.vsix，拷过来code --install-extension xxx.vsix。

离线安装这条路我强烈建议你提前走通一次，因为信创环境的网络策略往往比较严格，等你急着装扩展时才发现装不上，心态会很崩。

6.4 文件监视上限和中文路径

打开稍大的项目，编辑器提示 "Unable to watch for file changes"，或者干脆卡死。根因是 Linux 的 inotify 监视数量上限：

sudo sysctl fs.inotify.max_user_watches=524288

临时生效后，写进配置文件让它持久：

echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/99-vscode.conf

另一个更隐蔽的问题：项目路径里有中文。多数情况下能跑，但在处理编码、调用外部工具、生成临时文件时会出现乱码或找不到文件的情况。我的习惯是项目目录一律用英文和短横线，中文只出现在文档和注释里。

6.5 安全中心拦包、/home 分区太小

这两个放一起说，因为它们都属于"环境之外的意外"。装 deb 包时被安全中心拦下，去安全中心放行即可，不要试图关闭整个安全机制。

/home分区太小则是提前没看清楚的后果。UOS 装机时如果没手动分区，home 可能只分了几十 G，装几个 venv 加扩展缓存就告急。我的做法是给每个项目设定独立的 venv，用完就删；pip cache purge定期清缓存；扩展目录~/.vscode/extensions也要定期看看有没有用不上的残留。

7. 用一个真实小项目把环境跑通，顺便验证可迁移性

配完环境不算完，得用一个真项目验证一遍，确认调试、测试、依赖导出、迁移这几条链路都通。我用的验证项目很简单：一个带命令行入口、读配置文件、有单元测试的小工具，足够覆盖日常开发的主要动作。

7.1 目录结构约定

demo/ ├── .vscode/ │ ├── settings.json │ └── launch.json ├── src/ │ └── demo/ │ ├── __init__.py │ └── main.py ├── tests/ │ └── test_main.py ├── requirements.txt └── README.md

把代码放进src/demo而不是直接放根目录，看起来多一层，但能避免"本地能导入、打包后导入失败"这类问题，因为包结构清晰，导入路径不会和目录名撞车。配合前面launch.json里的PYTHONPATH设置，导入问题基本不会出现。

7.2 断点调试与测试跑通

在main.py里随便下个断点，按 F5，确认这几件事：断点能停住、变量面板能看到值、调用栈正常、内置终端能输入。这四件事只要有一件不对，说明解释器或者调试配置还有问题，别急着往前推进。

测试侧装 pytest：

source .venv/bin/activate pip install pytest python -m pytest -q

用python -m pytest而不是直接敲pytest，能保证用的是当前虚拟环境里的 pytest，避免系统里另有一份导致跑出不一致的结果。这个小习惯帮我省过好几次"明明本地过了，CI 挂了"的困惑。

7.3 依赖固化与迁移到同型号机器

验证的最后一关是迁移。我会导出依赖清单，特别注意区分"直接依赖"和"全部依赖"：

pip freeze > requirements.txt

然后在另一台同架构机器上重建：

python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt

如果目标机器架构不同，pip freeze出来的清单里那些带二进制扩展的包就会成为障碍。这时候我一般不再纠结 freeze，而是在requirements.txt里只写顶层依赖和宽松的版本区间，让目标机器自己解析，同时把 Python 版本要求写进 README。

我个人在这台浪潮 UOS 机器上的体会是：把"环境可复现"当成项目的一部分来做，而不是装完机器就完事。虚拟环境放在项目内、配置写进.vscode、依赖清单进版本控制、路径全部用相对变量——这套做法一旦成型，换台机器重新搭环境基本就是三条命令加一次解释器选择，十几分钟能搞定。反过来，如果依赖装在系统里、配置靠鼠标点、路径全是绝对路径，那换机器就是重来一遍，而且一定会漏东西。

最后再分享一个我常用的小技巧：在项目根目录放一个简短的SETUP.md，只写这台机器上必须做的非标准步骤，比如开发者模式怎么开、扩展怎么离线装、输入法环境变量怎么加。标准步骤谁都能查到，这些"只有在这个环境里才需要做"的东西，才是真正会忘的部分。