把 Python 项目从 Windows 开发机迁到 Ubuntu 服务器，难点通常不在“文件能不能传过去”，而在运行条件是否完整复现。真正影响成败的，是 Python 版本、虚拟环境、系统库、路径写法以及启动方式是否都匹配。下面按实际迁移顺序梳理一遍：先准备 Ubuntu 环境，再迁代码和依赖，最后处理配置、验证运行，并补上部署优化和常见故障判断点。
准备 Ubuntu 目标环境
先在目标机器上把基础环境装齐，这是后续所有步骤的前提。至少要有 Python3、pip、venv 和 git，避免项目代码传过去后还缺基础工具。
sudo apt update && sudo apt upgrade -y
# 更新系统包
sudo apt install python3 python3-pip python3-venv git -y
# 安装Python3、pip、venv及git这一步看起来简单，但很关键。很多迁移失败并不是业务代码有问题，而是目标机器没有准备好最基本的解释器和工具链。若你后面打算通过 Git 拉代码、用 venv 新建环境，或者安装依赖包，这几项都少不了。
迁移项目代码与目录
代码搬运常见有两种方式：用 Git 克隆仓库，或者直接用 scp/rsync 传目录。前者更适合持续维护，后者更适合一次性快速复制当前工作目录。
推荐方式：Git 克隆
如果项目本身已经在代码仓库里，优先使用 Git。它的好处是版本清晰，后续更新、回滚和协作都更方便。
git clone <项目仓库URL> /path/to/ubuntu/project_dir直接传输目录
如果项目还没有规范托管，或者你就是要把本地当前目录原样搬过去，可以直接传输。
scp -r /local/project/path username@ubuntu_ip:/remote/project/dir无论采用哪种方式，建议先确认 Ubuntu 侧的目标目录路径。后面创建虚拟环境、配置 Nginx、设置静态文件目录时，都会依赖这个路径，越早统一越省事。
虚拟环境怎么迁最稳妥
项目能不能跑起来，核心通常在依赖是否完整。虚拟环境迁移有三种常见做法，适用场景并不一样：最通用的是根据 requirements.txt 重装依赖，最快的是直接打包整个环境，完全离线时则更适合先准备 wheel 包。
方法 1：用 requirements.txt 重新安装
这是最通用、兼容性也最好的一种方式。先在源机器导出依赖清单：
source /path/to/source/venv/bin/activate
pip freeze > requirements.txt然后把 requirements.txt 放到目标机器，在项目目录下新建虚拟环境并重新安装：
cd /path/to/ubuntu/project_dir
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt这种方式的优点是最不依赖源环境本身，尤其适合从 Windows 迁到 Ubuntu 这种跨平台场景。因为很多包在不同系统上的二进制文件并不通用，重新安装通常比直接复制环境更稳。
方法 2：直接打包整个虚拟环境
如果源机器和目标机器的 Python 版本一致，而且依赖结构也没有明显平台差异，可以考虑直接打包虚拟环境，速度会更快。
源机器打包并传输：
tar -czvf venv.tar.gz /path/to/source/venv
scp venv.tar.gz username@ubuntu_ip:/remote/project/dir目标机器解压并激活：
tar -xzvf venv.tar.gz
source /path/to/ubuntu/project_dir/venv/bin/activate但要注意，这种方式对环境一致性要求更高。只要 Python 小版本、系统库或者编译依赖不匹配，就可能在运行时出错。因此它适合“已知两边环境非常接近”的情况，不适合作为默认方案。
方法 3：离线迁移 wheel 包
如果 Ubuntu 服务器不能访问外网，或者你所在环境对软件源有严格限制，就需要提前把依赖包准备好，再离线安装。
先在源机器下载 wheel 包并打包：
mkdir packages && pip wheel -w packages -r requirements.txt
tar -czvf packages.tar.gz packages
scp packages.tar.gz username@ubuntu_ip:/remote/project/dir到目标机器后解压、创建虚拟环境并离线安装：
tar -xzvf packages.tar.gz
cd /path/to/ubuntu/project_dir
python3 -m venv venv
source venv/bin/activate
pip install --no-index --find-links=./packages -r requirements.txt这一套的重点在于 --no-index 和 --find-links=./packages，它会让 pip 只从本地目录安装依赖，不再访问在线仓库。对内网部署或受限服务器来说，这通常是最可靠的办法。
系统依赖与项目配置要一起检查
即便 Python 依赖都装好了，项目也未必能直接运行。因为不少第三方包还依赖 Ubuntu 层面的系统库，这部分在 Windows 开发时往往不明显，迁移到 Linux 后就容易暴露出来。
例如，psycopg2 常常依赖 libpq-dev，opencv-python 可能需要 libopencv-dev。如果项目启动时报 ImportError，先别急着怀疑代码，优先检查系统库是否缺失。常见依赖可以先补齐：
sudo apt install libssl-dev libffi-dev libpq-dev libjpeg-dev libpng-dev -y路径适配
从 Windows 迁到 Ubuntu 时，一个高频问题就是硬编码路径。像 C:datafile.txt 这种写法，在 Ubuntu 上当然不能直接使用。需要检查项目配置、脚本和上传目录，把相关路径改成 Ubuntu 下可用的绝对路径或统一的配置项。
环境变量迁移
数据库连接串、密钥、运行模式这类信息，不建议继续写死在代码里。可以迁到 ~/.bashrc 或项目的 .env 文件中，再执行：
source ~/.bashrc这样做的好处是，环境差异和业务代码可以分开管理，后续换机器或扩容时也更清晰。
权限设置
如果项目目录权限不合适，日志、上传文件、静态资源等操作也可能失败。可以先给项目目录一个基础可用的权限：
chmod -R 755 /path/to/ubuntu/project_dir这不是所有场景下的最终权限方案，但足够作为迁移后的初步检查手段。若后续涉及专门的运行用户或更细粒度的写入目录，再单独调整会更稳妥。
运行验证与部署优化
环境和配置整理完后，先别急着上生产。第一步应该是在虚拟环境中直接把项目跑起来，确认代码、依赖和配置都已经对齐。
cd /path/to/ubuntu/project_dir
source venv/bin/activate
python manage.py runserver 0.0.0.0:8000Django 与 Flask 的额外检查
- 如果是 Django 项目，记得把
ALLOWED_HOSTS加上服务器 IP。开发阶段可以用['*']，但生产环境建议明确指定可访问的 IP 或域名。 - 如果是 Flask 项目，确认
FLASK_APP环境变量已经设置，例如：export FLASK_APP=app.py。
当开发服务器能够正常启动，再进入部署优化阶段会更清楚。否则一开始就接入反向代理，排障范围会被放大。
用 Gunicorn 替代开发服务器
Django 自带的开发服务器只适合调试，不适合承接正式流量。更常见的做法是换成 Gunicorn：
pip install gunicorn
gunicorn --workers 3 --bind 0.0.0.0:8000 project.wsgi--workers 3 和 --bind 0.0.0.0:8000 这类参数可以按机器资源和项目规模调整，但作为起步配置已经足够实用。
加一层 Nginx 反向代理
如果项目要长期提供服务，通常还会在 Gunicorn 前面加 Nginx。它负责接收外部请求、转发到应用进程，同时处理静态文件，整体结构会比直接暴露开发服务器更合理。
sudo apt install nginx -y
sudo nano /etc/nginx/sites-a vailable/your_project配置文件示例如下，实际使用时记得替换 your_domain_or_ip 和 project_dir：
server {
listen 80;
server_name your_domain_or_ip;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /static/ {
alias /path/to/ubuntu/project_dir/static/;
}
}启用配置并重启 Nginx：
sudo ln -s /etc/nginx/sites-a vailable/your_project /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx这里要额外留意原文中的路径写法 sites-a vailable，实际执行前应确认你的系统目录名称是否正确，避免因为路径拼写问题导致 Nginx 配置无法加载。
常见问题与排查思路
依赖安装失败
如果在 Ubuntu 上安装 Python 依赖很慢或频繁失败，可以先尝试镜像源，例如清华源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这类问题通常不是项目代码本身有错，而是下载链路或索引源不稳定。
Python 版本不兼容
迁移时最容易被忽略的一点，是源机器和目标机器的 Python 版本并不一致。如果项目原来跑在 Python 3.8 上，Ubuntu 端也最好显式安装对应版本并用它创建虚拟环境：
sudo apt install python3.8 python3.8-venv -y
python3.8 -m venv venv很多“依赖明明装上了却还是报错”的情况，最后都能追到解释器版本差异上。
缺少系统库
如果出现 ModuleNotFoundError: No module named '_ssl' 这类报错，往往说明缺的不是 Python 包，而是底层系统库。此时应结合错误信息补装对应依赖，例如 libssl-dev。
整体来看，这类迁移最稳的思路不是一次性复制所有东西，而是把“代码、Python 依赖、系统依赖、配置和启动方式”拆开逐项核对。只要这五部分一致，Windows 到 Ubuntu 的 Python 项目迁移通常就不会太难。
