在Apache部署Django虚拟环境项目启动失败：文件系统编码初始化错误

核心问题 #

Windows环境下，将virtualenv创建的Django项目部署到Apache时，启动Apache服务触发Python ModuleNotFoundError: No module named 'encodings'，同时存在Miniconda系统环境干扰的疑似问题。

错误日志 #

[Tue Mar 14 14:43:28.277072 2023] [mpm_winnt:notice] [pid 19800:tid 412] AH00455: Apache/2.4.56 (Win64) mod_wsgi/4.9.4 Python/3.10 configured -- resuming normal operations
[Tue Mar 14 14:43:28.278069 2023] [mpm_winnt:notice] [pid 19800:tid 412] AH00456: Apache Lounge VS17 Server built: Mar  6 2023 10:53:37
[Tue Mar 14 14:43:28.278069 2023] [core:notice] [pid 19800:tid 412] AH00094: Command line: 'C:\\Apache24\\bin\\httpd.exe -d C:/Apache24'
[Tue Mar 14 14:43:28.283041 2023] [mpm_winnt:notice] [pid 19800:tid 412] AH00418: Parent: Created child process 8896
Python path configuration:
  PYTHONHOME = (not set)
  PYTHONPATH = (not set)
  program name = 'python'
  isolated = 0
  environment = 1
  user site = 1
  import site = 1
  sys._base_executable = 'C:\\Apache24\\bin\\httpd.exe'
  sys.base_prefix = 'C:\\miniconda3'
  sys.base_exec_prefix = 'C:\\miniconda3'
  sys.platlibdir = 'lib'
  sys.executable = 'C:\\Apache24\\bin\\httpd.exe'
  sys.prefix = 'C:\\miniconda3'
  sys.exec_prefix = 'C:\\miniconda3'
  sys.path = [
    'C:\\miniconda3\\python310.zip',
    '.\\DLLs',
    '.\\lib',
    'C:\\Apache24\\bin',
  ]
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'

Current thread 0x000050e4 (most recent call first):
  <no Python frame>
[Tue Mar 14 14:43:28.946306 2023] [mpm_winnt:crit] [pid 19800:tid 412] AH00419: master_main: create child process failed. Exiting.

当前httpd.conf关键配置 #

LoadFile "C:/miniconda3/python310.dll"
LoadModule wsgi_module "C:/Django/venv/lib/site-packages/mod_wsgi/server/mod_wsgi.cp310-win_amd64.pyd"
WSGIPythonHome "C:/Django/venv/Scripts/python.exe"
WSGIPythonPath "C:/Django/Lib/site-packages" 

问题根源 #

1. WSGIPythonHome配置错误：该指令需指向Python环境的根目录，而非python.exe可执行文件路径，当前配置导致Python无法识别虚拟环境的目录结构。
2. Miniconda路径干扰：Apache启动时默认读取系统级Python路径（Miniconda），而非指定的虚拟环境路径。
3. WSGIPythonPath路径错误：配置指向的C:/Django/Lib/site-packages并非虚拟环境的包目录，正确路径应为C:/Django/venv/Lib/site-packages。

修复步骤 #

1. 修正httpd.conf中的Python环境配置 #

将相关配置段修改为：

# 加载虚拟环境的python.dll，替代Miniconda的dll
LoadFile "C:/Django/venv/Scripts/python310.dll"
LoadModule wsgi_module "C:/Django/venv/lib/site-packages/mod_wsgi/server/mod_wsgi.cp310-win_amd64.pyd"

# WSGIPythonHome指向虚拟环境根目录
WSGIPythonHome "C:/Django/venv"
# WSGIPythonPath包含虚拟环境包目录和Django项目根目录
WSGIPythonPath "C:/Django/venv/Lib/site-packages;C:/Django/project"

• 若虚拟环境Scripts目录无python310.dll，从Miniconda目录复制一份到该路径。
• WSGIPythonPath需包含虚拟环境包目录和Django项目根目录，确保Python能找到Django及相关模块。

2. 隔离Miniconda环境干扰 #

为Apache服务单独设置环境变量，强制使用虚拟环境的Python：

1. 打开Windows服务管理器，找到Apache服务（通常名为Apache2.4）。
2. 右键选择属性，切换到登录选项卡，选择NT AUTHORITY\LocalService账户。
3. 以管理员身份打开命令提示符，执行以下命令：

sc config Apache2.4 env= "PYTHONHOME=C:/Django/venv;PYTHONPATH=C:/Django/venv/Lib/site-packages;C:/Django/project"

3. 验证虚拟环境完整性 #

激活虚拟环境，确认Django和mod_wsgi已正确安装：

cd C:/Django/venv/Scripts
activate.bat
pip install django mod_wsgi

确保mod_wsgi版本与Python 3.10、Apache 2.4兼容。

4. 测试Apache启动 #

先在命令行验证配置语法：

cd C:/Apache24/bin
httpd.exe -t

若返回Syntax OK，再启动服务：

net start Apache2.4

关于Django Windows服务的额外说明 #

若后续尝试将Django做成Windows服务，需确保在虚拟环境内操作：

cd C:/Django/venv/Scripts
activate.bat
pip install pywin32
python your_service_script.py install

避免使用系统Python运行脚本，否则会出现模块导入错误。

内容的提问来源于stack exchange，提问作者j_kaden