详解如何在 Django 项目外部的 Python 脚本中安全初始化 Django 环境并导入模型

在 Django 项目之外运行独立的 Python 脚本——例如执行批量数据处理、文件导入或自动化任务——是开发中常见的需求。然而，许多开发者初次尝试时，常会遇到诸如 `ModuleNotFoundError: No module named 'snippets'` 的路径错误。问题的核心通常不在于代码逻辑，而在于是否在初始化 Django 环境前做好了充分的准备工作。关键在于，必须确保 Python 解释器能够定位到您的项目模块，并明确告知 Django 其配置文件的位置。

问题诊断：路径配置是关键

首先，让我们分析一个典型的项目结构，以明确问题所在：

Main-Project/
  database/          ← 外部脚本存放目录
    text-script.py
    text-files/
  django/            ← Django 项目根目录（包含 manage.py）
    django/
      settings.py    ← 实际的设置模块路径为 django.settings
    snippets/
      models.py

原始脚本中使用了 `sys.path.append(parent_dir)` 将 `Main-Project/` 添加到了模块搜索路径。但请注意，`snippets` 应用并非 `Main-Project/` 的直接子包，它实际位于 `django/snippets/` 路径下。因此，当 Python 尝试导入 `'django.snippets.models'` 时，自然无法找到该模块。正确的解决方案是，将Django 项目的根目录（即包含 `manage.py` 的 `django/` 文件夹）添加到 `sys.path`，而非其父级目录。

解决方案：修正后的健壮脚本

以下是一个经过优化和增强的 `text-script.py` 完整实现，它不仅修正了路径问题，还提升了脚本的稳定性和可维护性：

import os
import sys
import django
from django.conf import settings

# 1. 精准定位 Django 项目根目录（即包含 settings.py 的 django/ 目录）
current_dir = os.path.dirname(os.path.abspath(__file__))
project_root = os.path.join(current_dir, '..', 'django')  # ← 核心修正：指向 django/ 目录
project_root = os.path.abspath(project_root)
sys.path.append(project_root)

# 2. 配置并启动 Django 环境
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'django.settings')
django.setup()

# 3. ✅ 此时可安全导入 Django 模型（导入路径需与 INSTALLED_APPS 配置一致）
from snippets.models import Snippet  # 注意：现在直接使用 snippets，因为 django/ 已在 sys.path 中

def import_articles(directory):
    for filename in os.listdir(directory):
        if filename.endswith('.txt'):  # ⚠️ 修正拼写：endwith → endswith
            file_path = os.path.join(directory, filename)
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
            Snippet.objects.create(filename=filename, content=content)
            print(f"成功导入: {filename}")

if __name__ == '__main__':
    text_dir = os.path.join(current_dir, 'text-files')
    import_articles(text_dir)

核心要点与注意事项

脚本修改完成后，理解以下关键点有助于您灵活应对不同场景：

• ✅ 路径必须精确：`sys.path.append(project_root)` 必须指向 `django/` 目录（即 `Main-Project/django`），这是 Python 能够发现 `snippets` 等应用模块的基础。
• ✅ 设置模块名需准确：`DJANGO_SETTINGS_MODULE` 环境变量应设置为 `'django.settings'`（对应 `django/django/settings.py` 文件），切勿错误地写为 `'django.django.settings'`。
• ✅ 导入方式需对应：只要 `INSTALLED_APPS` 中已正确配置了 `'snippets.apps.SnippetsConfig'`，就可以直接使用 `from snippets.models` 导入，Django 会自动识别该应用。
• ⚠️ 初始化顺序至关重要：务必在导入任何 Django 模型之前调用 `django.setup()` 函数，否则 ORM 系统尚未就绪，必然导致错误。