SQLiteException在Android开发中出现频率并不低，很多开发者第一次遇到它时往往束手无策，因为异常信息有时候只有一句简短的英文描述，比如database or disk is full或者near xxx syntax error，很难直接看出问题根源。实际上这个异常的诱因高度集中在两类：一类是磁盘空间或存储状态异常，另一类是SQL语句本身写错了。本文将按照这两条主线，结合具体代码和排查步骤，把常见触发场景和解决办法完整梳理一遍。
一、磁盘空间不足导致的SQLiteException
1. 异常的典型表现
当设备存储空间耗尽时，SQLite在执行INSERT或UPDATE等写操作时会抛出类似android.database.sqlite.SQLiteException: database or disk is full (code 13)的异常。这个异常有一个比较隐蔽的特点：在开发阶段几乎不可能复现，因为测试机的存储空间通常是充足的，只有用户长期使用、缓存堆积之后才会在生产环境集中爆发。因此对这类问题的处理重点在于事前预防和运行时优雅降级，而不是等崩溃发生后再补救。
2. 如何检测剩余空间
在执行大批量写入之前，可以主动检测可用空间，避免盲目写入导致崩溃。下面是一段检测内部存储和外部存储剩余空间的示例代码：
public static long getAvailableInternalSpace(Context context) {
// 获取内部存储（数据分区）的可用字节数
File filesDir = context.getFilesDir();
StatFs stat = new StatFs(filesDir.getAbsolutePath());
long availableBytes = stat.getAvailableBytesLong();
return availableBytes;
}
public static void checkSpaceBeforeWrite(Context context, long needBytes) {
long available = getAvailableInternalSpace(context);
if (available < needBytes) {
// 空间不足，提前提示用户清理，而不是让SQLite抛异常
throw new IllegalStateException("存储空间不足，剩余: " + available);
}
}
需要注意，Android应用的数据目录一般位于/data/data/包名/databases/下，这个分区和系统数据分区共享空间，与外部存储的可用空间是两回事，所以检测时一定要针对正确的路径。
3. 清理空间的具体手段
确认是空间问题后，可以按优先级执行以下清理动作。首先是清理应用自身的缓存目录，调用context.getCacheDir()下的文件可以随时删除而不影响功能；其次是检查数据库的WAL文件，如果开启了PRAGMA journal_mode=WAL，在-wal和-shm文件没有正常合并的情况下可能占用数倍于主库的体积，此时执行一次PRAGMA wal_checkpoint(FULL)强制合并，能有效回收空间；最后可以考虑删掉数据库中的过期数据，配合VACUUM命令压缩文件体积，因为SQLite删除数据后文件大小不会自动缩减，只有执行VACUUM才会真正归还磁盘空间给操作系统。
二、SQL语法错误导致的SQLiteException
1. 关键字冲突是最常见的坑
当表名或字段名与SQLite保留字重名时，建表或查询会直接报语法错误，比如near "order": syntax error。像order、group、index、table、select这些都是保留字。解决办法要么改名，要么用方括号或反引号包裹，例如写成CREATE TABLE [order] (id INTEGER PRIMARY KEY)。建议直接避免使用保留字命名，一劳永逸。
2. 字符串拼接引发的语法问题
很多开发者习惯用字符串拼接构造SQL，当插入的内容含有单引号时就会破坏语句结构，例如：
// 错误示范：内容中带单引号会导致语法错误
String name = "O'Brien";
db.execSQL("INSERT INTO user (name) VALUES ('" + name + "')");
// 正确做法：使用参数化查询，问号占位符由系统安全绑定
ContentValues values = new ContentValues();
values.put("name", name);
db.insert("user", null, values);
参数化查询不仅能规避语法错误，还能顺带防止SQL注入，是Android官方推荐的标准写法。原生SQLiteDatabase提供insert、update、delete和query方法，基本可以覆盖日常需求，只有在复杂查询时才需要手写SQL，此时也应使用rawQuery配合占位符参数数组。
3. 建表语句字段类型或约束写错
SQLite对类型要求宽松，但约束部分的语法是严格的。常见错误包括把AUTOINCREMENT写成AUTO_INCREMENT（这是MySQL的写法）、遗漏INTEGER PRIMARY KEY的组合要求、在NOT NULL后缺少默认值等。排查这类问题时，最直接的办法是借助adb shell把数据库文件拉到本地，用图形化工具打开后直接执行那条出错的SQL，错误信息会比在Logcat里直观得多。
三、其他容易误判为磁盘满或语法错的场景
1. 数据库文件损坏
如果异常信息是database disk image is malformed，这既不是磁盘满也不是语法错误，而是库文件本身损坏了，常见诱因包括写入过程中进程被杀、设备断电、多进程并发访问同一个库等。轻度的损坏可以尝试执行PRAGMA integrity_check确认，然后用REINDEX或导出重建的方式修复；如果应用配置了android:allowBackup="true"，还可能因为备份恢复时文件不完整导致损坏，建议把数据库文件加入备份排除规则。
2. 多进程并发访问
从Android平台早期开始，多个进程同时打开同一个SQLite库就可能引发各类异常，包括锁异常和被误读为磁盘问题的错误。如果业务上必须多进程访问，应使用SQLiteDatabase.OPEN_READWRITE配合enableWriteAheadLogging谨慎处理，或者干脆通过ContentProvider统一收口访问入口，让数据库只在单一进程中被操作。
3. 排查时的通用步骤建议
遇到SQLiteException时，建议按固定顺序排查：先看异常消息中的code和具体描述判断类别；再检查Logcat中完整的SQL语句原文，很多语法错误一眼就能看出拼接问题；然后确认设备剩余空间和数据库文件大小是否异常膨胀；最后在本地环境用相同SQL复现验证。养成先看消息、再看SQL、再看环境的习惯，绝大多数SQLiteException都能在几分钟内定位到根因。
总结来看，SQLiteException虽然名目繁多，但根因高度集中。磁盘满的问题靠主动检测、定期清理和WAL管理来预防，语法错误靠参数化查询和规范命名来杜绝，再加上对数据库损坏和并发问题的基本认知，就能把这个异常的控制权牢牢握在自己手里。
SQLiteException数据库异常Android数据库修改时间：2026-09-01 10:49:08