本文详解如何在 Django 项目外部独立目录中编写 Python 脚本，安全初始化 Django 环境、导入自定义模型并操作同一数据库，重点解决 ModuleNotFoundError: No module named 'snippets' 等路径与配置错误。
本文详解如何在 django 项目外部独立目录中编写 python 脚本，安全初始化 django 环境、导入自定义模型并操作同一数据库，重点解决 `modulenotfounderror: no module named 'snippets'` 等路径与配置错误。
在实际开发中，常需脱离 Django Web 服务运行独立数据处理脚本（如批量导入文本、定时清洗数据等）。但若脚本位于项目根目录外的独立子目录（如 database/），直接导入模型会因 Python 模块路径和 Django 配置未正确加载而失败——典型报错为 ModuleNotFoundError: No module named 'snippets' 或 django.core.exceptions.AppRegistryNotReady。
根本原因在于：Django 的模块发现机制依赖于 PYTHONPATH 和 DJANGO_SETTINGS_MODULE 的协同生效，而 sys.path.append() 添加的路径必须精确指向 Django 项目的根目录（即包含 manage.py 或 settings.py 所在包的上层目录），而非任意父级目录。
以你的项目结构为例：
Main-Project/
database/ ← 脚本所在目录（非 Django 根）
text-script.py
text-files/
django/ ← Django 项目实际根目录（含 django/settings.py 和 snippets/）
django/
settings.py
snippets/
models.py
你最初将 parent_dir（即 Main-Project/）加入 sys.path，但该目录下并无 snippets 包；snippets 实际位于 django/snippets/ 下，因此 Python 无法解析 from django.snippets.models import Snippet。正确做法是将 django/ 目录（即 Django 项目根）加入 sys.path，并确保 DJANGO_SETTINGS_MODULE 指向其内部设置模块。
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
以下是修正后的 text-script.py 完整代码（含健壮性增强）：
import os
import sys
import django
from django.conf import settings
# 1. 定位 Django 项目根目录（即包含 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 设置模块（注意路径层级：django.django.settings 表示 django/ 目录下的 django/settings.py）
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'django.settings')
# 3. 初始化 Django（必须在导入模型前调用）
django.setup()
# 4. ✅ 此时可安全导入模型
from snippets.models import Snippet # 注意：无需 'django.snippets'，因已将 'django/' 加入 path
def import_articles(directory):
for filename in os.listdir(directory):
if filename.endswith('.txt'): # ⚠️ 修复拼写：endwith → endswith
file_path = os.path.join(directory, filename)
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
# 使用 get_or_create 避免重复插入（可选增强）
Snippet.objects.get_or_create(
filename=filename,
defaults={'content': content}
)
print(f"✅ Imported: {filename}")
except Exception as e:
print(f"❌ Failed to import {filename}: {e}")
if __name__ == '__main__':
text_dir = os.path.join(current_dir, 'text-files')
if not os.path.isdir(text_dir):
raise RuntimeError(f"Text directory not found: {text_dir}")
import_articles(text_dir)
关键要点与注意事项：
- ✅ 路径精准性：sys.path.append() 必须添加 Django 项目根目录（django/），而非 Main-Project/。这是解决 ModuleNotFoundError 的核心。
- ✅ DJANGO_SETTINGS_MODULE 格式：值为 'django.settings'（假设 django/settings.py 存在），而非 'django.django.settings' —— 后者仅在 django/ 目录下还嵌套了一层 django/ 包时才需要（如标准 mysite/mysite/settings.py 结构）。
- ✅ django.setup() 不可省略：它触发 Django 应用注册与数据库配置加载，必须在任何模型导入前调用。
- ⚠️ 编码与异常处理：显式指定 encoding='utf-8' 防止中文乱码；包裹文件操作在 try-except 中提升脚本鲁棒性。
- ? 验证安装应用：确保 INSTALLED_APPS 中 snippets.apps.SnippetsConfig 已正确注册（你已做到），且 snippets/apps.py 中的 default_app_config（如使用 Django
- ? 本地测试建议：在 text-script.py 同级执行 python -c "import snippets; print(snippets.__file__)" 可快速验证模块是否可导入。
通过以上配置，你的外部脚本即可完全复用 Django 项目的数据库连接、模型逻辑与 ORM 功能，实现安全、可维护的数据批处理任务。
