只狼图文避坑指南：3步修复复制代码跑不通

复制来的代码跑不通不知道怎么调？别慌，这通常是环境依赖、路径配置或版本差异导致的。这篇只狼图文避坑指南，将带你从零基础搭建一个可复现的项目，彻底解决“看着会、上手废”的难题。

项目目标

我们要从零搭建一个基于 Python 的“只狼图文解析工具”。这个项目的核心目标不是去破解游戏，而是演示如何处理本地静态资源。假设你手头有一批只狼相关的攻略图片（PNG/JPG），你需要一个脚本，自动扫描文件夹，提取图片文件名中的关键词（如“Boss”、“武器”、“地图”），并生成一个 JSON 格式的索引文件。

为什么选这个场景？因为它覆盖了文件读写、正则表达式、异常处理、配置管理四个后端开发高频考点。很多初学者复制网上代码，一运行就报 FileNotFoundError 或 PermissionError，根源在于他们忽略了操作系统差异和权限控制。

目录结构

工程化开发的第一步，是规范目录结构。混乱的文件摆放是调试噩梦的源头。请按照以下结构创建文件夹：

project_root/
├── src/
│   ├── __init__.py
│   ├── config.py      # 配置管理
│   ├── parser.py      # 核心解析逻辑
│   └── utils.py       # 工具函数
├── data/
│   └── images/        # 存放测试图片
├── output/            # 存放生成的JSON索引
├── tests/
│   └── test_parser.py # 单元测试
├── requirements.txt   # 依赖清单
└── main.py            # 入口文件

注意，data/images 目录必须在代码运行前手动创建并放入测试图片。很多教程省略了这一步，导致新手运行代码时直接崩溃。requirements.txt 中只需包含 Pillow（用于处理图片元数据，可选）和 pathlib（Python 3.4+ 内置，无需安装）。

核心代码实现

1. 配置管理：避免硬编码

硬编码是代码跑不通的常见原因之一。路径写死在代码里，换个电脑就失效。

src/config.py:

import os
from pathlib import Path# 获取项目根目录，确保相对路径正确
BASE_DIR = Path(__file__).resolve().parent.parent# 定义关键路径
IMAGE_DIR = BASE_DIR / "data" / "images"
OUTPUT_DIR = BASE_DIR / "output"# 确保输出目录存在
def ensure_dirs():if not OUTPUT_DIR.exists():OUTPUT_DIR.mkdir(parents=True)# 支持的文件扩展名
SUPPORTED_EXTS = {'.png', '.jpg', '.jpeg'}

逐行讲解：

Path(__file__).resolve().parent.parent：这是获取项目根目录的标准写法。无论你从哪个目录启动脚本，它都能正确找到 project_root。
ensure_dirs()：在运行前检查并创建输出目录。这一步能避免 PermissionError。

2. 核心解析逻辑：正则与异常处理

src/parser.py 是核心。我们要从文件名中提取信息。假设文件名格式为 sekiro_boss_ryu.jpg。

import re
import json
from pathlib import Path
from .config import IMAGE_DIR, SUPPORTED_EXTS, ensure_dirs# 定义正则模式：匹配 sekiro_ 开头的文件名
# 组1：类别(boss/weapon/map)
# 组2：具体名称
PATTERN = re.compile(r'sekiro_(boss|weapon|map)_(.+)\.(png|jpg|jpeg)$', re.IGNORECASE)def parse_images(image_dir: Path):"""扫描目录，解析文件名，返回字典列表"""ensure_dirs()results = []# 遍历目录中的所有文件for file_path in image_dir.iterdir():# 跳过非文件和不支持的扩展名if not file_path.is_file():continueif file_path.suffix.lower() not in SUPPORTED_EXTS:continue# 尝试匹配正则match = PATTERN.match(file_path.name)if match:category = match.group(1)name = match.group(2)# 构建记录record = {"category": category,"name": name,"file_path": str(file_path.relative_to(image_dir)),"size_kb": round(file_path.stat().st_size / 1024, 2)}results.append(record)else:# 记录未匹配的文件，便于调试print(f"[WARN] 未匹配的文件: {file_path.name}")return resultsdef save_to_json(data: list, output_path: Path):"""保存结果到JSON"""output_path.parent.mkdir(parents=True, exist_ok=True)with open(output_path, 'w', encoding='utf-8') as f:json.dump(data, f, ensure_ascii=False, indent=4)

避坑重点：

re.IGNORECASE：文件名可能有大写，必须忽略大小写。
file_path.stat().st_size：获取文件大小。注意，如果文件被其他进程占用，这里可能抛出 OSError。在实际生产中，建议加上 try-except 块。
ensure_ascii=False：JSON 中文乱码的罪魁祸首。必须设置此项，否则生成的 JSON 中中文会变成 \uXXXX 转义序列。

3. 入口文件：组装逻辑

main.py:

from src.config import IMAGE_DIR, OUTPUT_DIR
from src.parser import parse_images, save_to_json
from pathlib import Pathdef main():print(f"开始扫描: {IMAGE_DIR}")# 检查图片目录是否存在if not IMAGE_DIR.exists():print(f"错误: 目录 {IMAGE_DIR} 不存在。请手动创建并放入图片。")return# 解析图片data = parse_images(IMAGE_DIR)if not data:print("警告: 未找到任何符合格式的图片。请检查文件名是否符合 sekiro_type_name.ext 格式。")return# 保存结果output_file = OUTPUT_DIR / "index.json"save_to_json(data, output_file)print(f"成功解析 {len(data)} 张图片，结果已保存至: {output_file}")if __name__ == "__main__":main()

运行与测试

1. 准备测试数据

在 data/images 目录下创建以下文件（内容任意，只需文件名正确）：

sekiro_boss_ryu.jpg
sekiro_weapon_odachi.png
sekiro_map_sekiro.jpg
invalid_file.txt (用于测试过滤)
sekiro_unknown_test.jpg (用于测试正则未匹配警告)

2. 运行代码

在项目根目录执行：

python main.py

预期输出：

开始扫描: /path/to/project_root/data/images
[WARN] 未匹配的文件: invalid_file.txt
[WARN] 未匹配的文件: sekiro_unknown_test.jpg
成功解析 3 张图片，结果已保存至: /path/to/project_root/output/index.json

3. 验证结果

打开 output/index.json，应看到类似以下内容：

[{"category": "boss","name": "ryu","file_path": "sekiro_boss_ryu.jpg","size_kb": 12.5},...
]

常见错误排查：

ModuleNotFoundError: No module named 'src'：确保你在 project_root 目录下运行命令，且 src 目录下有 __init__.py 文件。
PermissionError: [WinError 5] 拒绝访问：Windows 下，如果文件正在被其他程序（如图片查看器）打开，无法读取大小。关闭相关程序后重试。

优化扩展

1. 添加日志系统

生产环境不能只用 print。引入 logging 模块。

src/logger.py:

import loggingdef setup_logger():logging.basicConfig(level=logging.INFO,format='%(asctime)s - %(levelname)s - %(message)s',handlers=[logging.FileHandler("app.log"),logging.StreamHandler()])return logging.getLogger(__name__)

在 parser.py 中替换 print 为 logger.warning() 和 logger.info()。

2. 支持命令行参数

使用 argparse 允许用户指定输入输出目录。

import argparsedef main():parser = argparse.ArgumentParser(description='只狼图文解析工具')parser.add_argument('--input', '-i', default='data/images', help='输入目录')parser.add_argument('--output', '-o', default='output', help='输出目录')args = parser.parse_args()# 动态更新配置# ... (此处省略动态配置逻辑，实际项目中需重构 config 为类或函数)

3. 单元测试

tests/test_parser.py:

import unittest
import tempfile
import os
from src.parser import parse_images
from pathlib import Pathclass TestParser(unittest.TestCase):def setUp(self):# 创建临时目录self.temp_dir = tempfile.TemporaryDirectory()self.test_dir = Path(self.temp_dir.name)# 创建测试文件(self.test_dir / "sekiro_boss_ryu.jpg").touch()(self.test_dir / "invalid.txt").touch()def tearDown(self):self.temp_dir.cleanup()def test_parse_images(self):results = parse_images(self.test_dir)self.assertEqual(len(results), 1)self.assertEqual(results[0]["category"], "boss")self.assertEqual(results[0]["name"], "ryu")if __name__ == '__main__':unittest.main()

运行测试：