SQLite “file is not a database” — 文件损坏或类型错误

症状

遇到“SQLite “file is not a database” — 文件损坏或类型错误”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• 打开路径时 SQLite 报 “file is not a database”
• 该文件近期被下载或恢复
• 应用创建一个 0 字节文件后读取失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

head -c 16 app.db | xxd

合法 SQLite 文件以魔数 “SQLite format 3\0” 开头；其他内容都不是 SQLite。

步骤 2

ls -l app.db && file app.db

0 字节或 HTML 文件即揭示路径错误或下载失败。

常见诱因（按出现频率排序）：

• 该文件根本不是 SQLite（把 HTML 错误页存成 .db，或格式不同）
• 路径错误，指向了无关的既有文件
• 因写入中断或磁盘问题导致数据库头损坏

根因

SQLite 通过 16 字节魔数头识别数据库。若该头缺失——因文件是 HTML、其他格式、空文件或已损坏——把它当数据库打开便会报 “file is not a database”。

修复

指向正确路径，确保文件是真正的 SQLite 数据库，使用前校验头；若确认损坏，则从备份恢复并检查文件系统。

注意：通过删除并重建来“修复”损坏数据库会丢数据；应先备份损坏文件。

# verify the magic header before opening
head -c 16 app.db | xxd
# expected: 5351 4c69 7465 2066 6f72 6d61 7420 3300  (

# integrity check after opening
sqlite3 app.db 'PRAGMA integrity_check;'

# recover from a good backup rather than recreating
cp app.db.bak app.db

验证

打开正确文件并确认 PRAGMA integrity_check 返回 ok；断言头与魔数一致。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。