1. 为什么要把 SQLite 数据库放到 SD 卡加载做 Android 开发时SQLite 默认把 db 文件放在data/data/包名/databases/目录下这个路径普通用户和第三方工具都很难直接访问。如果你需要预置一份带数据的数据库、或者想让测试同学能随时替换 db 文件排查问题把数据库放到外部存储也就是大家习惯说的 SD 卡路径再让应用去加载会方便很多。这篇要解决的核心问题就是Android 应用如何从 SD 卡加载 SQLite 数据库文件。适合已经会写基本 SQLite 增删改查、但卡在“外部 db 文件怎么让 SQLiteOpenHelper 认”的开发者。完整流程会覆盖三块权限声明、路径拼接、用自定义 Context 打开外部库最后再补上 SQL 注入防护和真机验证步骤。很多人第一次尝试会直接改SQLiteOpenHelper的构造参数把 name 传成 SD 卡绝对路径结果发现系统还是去databases/目录找文件。原因在于SQLiteOpenHelper内部最终调用的是Context.openOrCreateDatabase()而默认实现固定拼的是内置路径。所以正确思路不是改 Helper而是换掉 Context 的实现让它去打开我们指定的外部文件。下面按可复制的顺序一步步来。2. 前置准备权限、路径与 TaoToken 辅助调试2.1 AndroidManifest 权限声明从 Android 6.0API 23开始外部存储读写属于危险权限除了在清单里声明还要在运行时动态申请。清单里先加上manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.sqldemo !-- Android 12 及以下读取外部存储 -- uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion28 / !-- Android 13 及以上按媒体类型细分这里用管理外部存储的通用声明 -- uses-permission android:nameandroid.permission.MANAGE_EXTERNAL_STORAGE tools:ignoreScopedStorage / application android:requestLegacyExternalStoragetrue ... /application /manifest注意requestLegacyExternalStoragetrue只在 Android 10 上有效Android 11 起分区存储强制生效。如果你的目标机型是 Android 11建议把 db 放在应用自己的外部目录Android/data/包名/下这个路径不需要额外存储权限卸载应用时也会一起清掉最省心。2.2 运行时申请权限private static final int REQ_STORAGE 1001; private void requestStoragePermission() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { if (checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE) ! PackageManager.PERMISSION_GRANTED) { requestPermissions( new String[]{Manifest.permission.READ_EXTERNAL_STORAGE}, REQ_STORAGE); } } }2.3 用 TaoToken 快速验证模型生成的 SQL 片段写 DAO 的时候经常要临时验证一段 SQL 或让模型帮忙改写查询语句。我平时会用 TaoToken 的模型对话来快速过一遍语法省得反复编译。它的接入地址是https://taotoken.net/api控制台在 consoleAPI Key 在 api-keys 页面生成。如果你只是偶尔问几句 SQL用模型对话就够了要是长期做 Android 编码、想让 Agent 帮你批量改 DAO可以看下 Coding Plan。接入文档在 doc配置方式照着填就行。3. 可复制配置自定义 Context 打开 SD 卡数据库3.1 先理解默认路径是怎么拼出来的SQLiteOpenHelper.getWritableDatabase()最终会走到getDatabaseLocked()里面关键一句是db mContext.openOrCreateDatabase(mName, mode, mFactory, mErrorHandler);而ContextImpl的实现是File f getDatabasePath(name); // data/data/包名/databases/name SQLiteDatabase.openDatabase(f.getPath(), factory, flags, errorHandler);所以只要我们把mContext换成一个重写了openOrCreateDatabase的ContextWrapper就能让它去打开 SD 卡上的文件。3.2 自定义 DataBaseContextpublic class DataBaseContext extends ContextWrapper { public DataBaseContext(Context base) { super(base); } Override public SQLiteDatabase openOrCreateDatabase(String name, int mode, SQLiteDatabase.CursorFactory factory, DatabaseErrorHandler errorHandler) { // 拼接外部存储路径Android/data/包名/database/xxx.db String dbPath getExternalFilesDir(database).getAbsolutePath() File.separator name .db; File file new File(dbPath); if (!file.exists()) { throw new IllegalStateException(DB file not exists: dbPath); } // 直接打开外部 db 文件 return SQLiteDatabase.openOrCreateDatabase(dbPath, null); } }这里用getExternalFilesDir(database)而不是硬编码/sdcard/好处是路径随应用包名自动生成Android 11 也不需要额外权限。3.3 改造 SQLiteOpenHelper 的调用方式public class SQLiteDBHelper extends SQLiteOpenHelper { public static final String DATABASE_NAME mango; public static final String TABLE_USER user; private static final int DATABASE_VERSION 1; public SQLiteDBHelper(Context context) { // 关键传入自定义 Context super(new DataBaseContext(context), DATABASE_NAME, null, DATABASE_VERSION); } Override public void onCreate(SQLiteDatabase db) { String sql create table if not exists TABLE_USER (uid integer primary key autoincrement, name varchar(20), sex varchar(4), role varchar(10)); db.execSQL(sql); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(drop table if exists TABLE_USER); onCreate(db); } }3.4 启动时把 db 从 assets/raw 拷到外部目录private void copyDbIfNeeded() { File dbFile new File(getExternalFilesDir(database), mango.db); if (dbFile.exists()) return; try (InputStream is getResources().openRawResource(R.raw.mango); FileOutputStream fos new FileOutputStream(dbFile)) { byte[] buffer new byte[4096]; int len; while ((len is.read(buffer)) ! -1) { fos.write(buffer, 0, len); } fos.flush(); } catch (IOException e) { Log.e(DB, copy db failed, e); } }4. 验证请求真机读取表数据并测试注入4.1 参数化查询示例public User getUser(String uid) { SQLiteDatabase db mHelper.getReadableDatabase(); User user new User(); // 用 ? 占位符不要字符串拼接 String sql select * from SQLiteDBHelper.TABLE_USER where uid ?; Cursor cursor db.rawQuery(sql, new String[]{uid}); while (cursor.moveToNext()) { user.setUid(cursor.getString(cursor.getColumnIndexOrThrow(uid))); user.setName(cursor.getString(cursor.getColumnIndexOrThrow(name))); user.setSex(cursor.getString(cursor.getColumnIndexOrThrow(sex))); user.setRole(cursor.getString(cursor.getColumnIndexOrThrow(role))); } cursor.close(); db.close(); return user; }4.2 真机验证步骤第一步用 SQLiteManager 之类的可视化工具建好mango.db建一张user表并插入几条测试数据比如(1, tom, 1, 2)。第二步把 db 文件通过 adb 推到应用外部目录adb push mango.db /sdcard/Android/data/com.example.sqldemo/files/database/mango.db第三步启动应用调用getUser(1)在 Logcat 里打印结果。如果看到User{uid1, nametom, ...}说明外部 db 加载成功。第四步做注入测试。把 uid 传成1 or 11因为用了?占位符SQLite 会把它当成普通字符串处理查询结果为空注入无效。如果换成拼接写法where uid uid 这条语句就会变成where uid 1 or 11全表数据都会被查出来这就是典型的注入漏洞。4.3 用 TaoToken 验证 SQL 语义如果对某条查询的语义拿不准可以把 SQL 贴到 模型对话 里让模型解释执行计划或者用 ClaudeCodeAnthropic 在本地跑一段脚本验证。接入方式参考 docAPI Key 从 api-keys 取。5. 本篇常见错排查5.1 报错 “DB file not exists”最常见的原因是路径拼错了。getExternalFilesDir(database)返回的是/storage/emulated/0/Android/data/包名/files/database注意中间有个files目录。如果你 adb push 的时候漏了files文件就放错位置了。用adb shell ls逐层确认。5.2 报错 “attempt to write a readonly database”外部存储上的 db 文件权限不对。用 adb push 过去的文件默认属主是 shell应用进程没有写权限。解决办法是 push 之后执行adb shell chmod 666 /sdcard/Android/data/com.example.sqldemo/files/database/mango.db或者干脆在应用内用FileOutputStream拷贝这样文件属主就是应用自己。5.3 版本号不匹配导致 onUpgrade 被反复调用SQLiteOpenHelper构造时传的DATABASE_VERSION必须和外部 db 文件里记录的版本号一致。如果外部 db 是用工具建的默认版本号是 0而你在代码里传了 1第一次打开就会触发onUpgrade把表删了重建。建议建库时就把版本号设成和代码一致或者在onUpgrade里做兼容判断。5.4 查询返回空 Cursor先确认表名和字段名大小写是否一致SQLite 对表名大小写不敏感但字段名敏感。再用cursor.getCount()打印行数如果为 0说明数据没插进去或者 where 条件写错了。可以临时把 SQL 改成select * from user看能不能查到数据。5.5 SQL 注入测试没生效如果你用的是execSQL(sql, bindArgs)或rawQuery(sql, selectionArgs)注入本来就该无效这是正确行为。如果注入生效了说明代码里某处用了字符串拼接全局搜一下 uid 这类写法全部改成占位符。6. 继续深入把外部 db 加载接进你的工程到这里从 SD 卡加载 SQLite 数据库的完整链路就通了清单声明权限、自定义ContextWrapper重写openOrCreateDatabase、启动时拷贝 db 文件、参数化查询防注入、真机验证读取和注入测试。实际项目里我建议把DataBaseContext和SQLiteDBHelper封装成一个DbManager单例避免每次 new Helper 都重新打开文件。如果你在接入过程中遇到路径拼接或权限相关的报错可以到 API Keys 生成一个 Key配合 接入文档 里的示例让模型帮你逐行排查。长期做 Android 编码的话Coding Plan 会更顺手Agent 能直接读你的 DAO 文件给出修改建议。
1. 为什么要把 SQLite 数据库放到 SD 卡加载做 Android 开发时SQLite 默认把 db 文件放在data/data/包名/databases/目录下这个路径普通用户和第三方工具都很难直接访问。如果你需要预置一份带数据的数据库、或者想让测试同学能随时替换 db 文件排查问题把数据库放到外部存储也就是大家习惯说的 SD 卡路径再让应用去加载会方便很多。这篇要解决的核心问题就是Android 应用如何从 SD 卡加载 SQLite 数据库文件。适合已经会写基本 SQLite 增删改查、但卡在“外部 db 文件怎么让 SQLiteOpenHelper 认”的开发者。完整流程会覆盖三块权限声明、路径拼接、用自定义 Context 打开外部库最后再补上 SQL 注入防护和真机验证步骤。很多人第一次尝试会直接改SQLiteOpenHelper的构造参数把 name 传成 SD 卡绝对路径结果发现系统还是去databases/目录找文件。原因在于SQLiteOpenHelper内部最终调用的是Context.openOrCreateDatabase()而默认实现固定拼的是内置路径。所以正确思路不是改 Helper而是换掉 Context 的实现让它去打开我们指定的外部文件。下面按可复制的顺序一步步来。2. 前置准备权限、路径与 TaoToken 辅助调试2.1 AndroidManifest 权限声明从 Android 6.0API 23开始外部存储读写属于危险权限除了在清单里声明还要在运行时动态申请。清单里先加上manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.sqldemo !-- Android 12 及以下读取外部存储 -- uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion28 / !-- Android 13 及以上按媒体类型细分这里用管理外部存储的通用声明 -- uses-permission android:nameandroid.permission.MANAGE_EXTERNAL_STORAGE tools:ignoreScopedStorage / application android:requestLegacyExternalStoragetrue ... /application /manifest注意requestLegacyExternalStoragetrue只在 Android 10 上有效Android 11 起分区存储强制生效。如果你的目标机型是 Android 11建议把 db 放在应用自己的外部目录Android/data/包名/下这个路径不需要额外存储权限卸载应用时也会一起清掉最省心。2.2 运行时申请权限private static final int REQ_STORAGE 1001; private void requestStoragePermission() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { if (checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE) ! PackageManager.PERMISSION_GRANTED) { requestPermissions( new String[]{Manifest.permission.READ_EXTERNAL_STORAGE}, REQ_STORAGE); } } }2.3 用 TaoToken 快速验证模型生成的 SQL 片段写 DAO 的时候经常要临时验证一段 SQL 或让模型帮忙改写查询语句。我平时会用 TaoToken 的模型对话来快速过一遍语法省得反复编译。它的接入地址是https://taotoken.net/api控制台在 consoleAPI Key 在 api-keys 页面生成。如果你只是偶尔问几句 SQL用模型对话就够了要是长期做 Android 编码、想让 Agent 帮你批量改 DAO可以看下 Coding Plan。接入文档在 doc配置方式照着填就行。3. 可复制配置自定义 Context 打开 SD 卡数据库3.1 先理解默认路径是怎么拼出来的SQLiteOpenHelper.getWritableDatabase()最终会走到getDatabaseLocked()里面关键一句是db mContext.openOrCreateDatabase(mName, mode, mFactory, mErrorHandler);而ContextImpl的实现是File f getDatabasePath(name); // data/data/包名/databases/name SQLiteDatabase.openDatabase(f.getPath(), factory, flags, errorHandler);所以只要我们把mContext换成一个重写了openOrCreateDatabase的ContextWrapper就能让它去打开 SD 卡上的文件。3.2 自定义 DataBaseContextpublic class DataBaseContext extends ContextWrapper { public DataBaseContext(Context base) { super(base); } Override public SQLiteDatabase openOrCreateDatabase(String name, int mode, SQLiteDatabase.CursorFactory factory, DatabaseErrorHandler errorHandler) { // 拼接外部存储路径Android/data/包名/database/xxx.db String dbPath getExternalFilesDir(database).getAbsolutePath() File.separator name .db; File file new File(dbPath); if (!file.exists()) { throw new IllegalStateException(DB file not exists: dbPath); } // 直接打开外部 db 文件 return SQLiteDatabase.openOrCreateDatabase(dbPath, null); } }这里用getExternalFilesDir(database)而不是硬编码/sdcard/好处是路径随应用包名自动生成Android 11 也不需要额外权限。3.3 改造 SQLiteOpenHelper 的调用方式public class SQLiteDBHelper extends SQLiteOpenHelper { public static final String DATABASE_NAME mango; public static final String TABLE_USER user; private static final int DATABASE_VERSION 1; public SQLiteDBHelper(Context context) { // 关键传入自定义 Context super(new DataBaseContext(context), DATABASE_NAME, null, DATABASE_VERSION); } Override public void onCreate(SQLiteDatabase db) { String sql create table if not exists TABLE_USER (uid integer primary key autoincrement, name varchar(20), sex varchar(4), role varchar(10)); db.execSQL(sql); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(drop table if exists TABLE_USER); onCreate(db); } }3.4 启动时把 db 从 assets/raw 拷到外部目录private void copyDbIfNeeded() { File dbFile new File(getExternalFilesDir(database), mango.db); if (dbFile.exists()) return; try (InputStream is getResources().openRawResource(R.raw.mango); FileOutputStream fos new FileOutputStream(dbFile)) { byte[] buffer new byte[4096]; int len; while ((len is.read(buffer)) ! -1) { fos.write(buffer, 0, len); } fos.flush(); } catch (IOException e) { Log.e(DB, copy db failed, e); } }4. 验证请求真机读取表数据并测试注入4.1 参数化查询示例public User getUser(String uid) { SQLiteDatabase db mHelper.getReadableDatabase(); User user new User(); // 用 ? 占位符不要字符串拼接 String sql select * from SQLiteDBHelper.TABLE_USER where uid ?; Cursor cursor db.rawQuery(sql, new String[]{uid}); while (cursor.moveToNext()) { user.setUid(cursor.getString(cursor.getColumnIndexOrThrow(uid))); user.setName(cursor.getString(cursor.getColumnIndexOrThrow(name))); user.setSex(cursor.getString(cursor.getColumnIndexOrThrow(sex))); user.setRole(cursor.getString(cursor.getColumnIndexOrThrow(role))); } cursor.close(); db.close(); return user; }4.2 真机验证步骤第一步用 SQLiteManager 之类的可视化工具建好mango.db建一张user表并插入几条测试数据比如(1, tom, 1, 2)。第二步把 db 文件通过 adb 推到应用外部目录adb push mango.db /sdcard/Android/data/com.example.sqldemo/files/database/mango.db第三步启动应用调用getUser(1)在 Logcat 里打印结果。如果看到User{uid1, nametom, ...}说明外部 db 加载成功。第四步做注入测试。把 uid 传成1 or 11因为用了?占位符SQLite 会把它当成普通字符串处理查询结果为空注入无效。如果换成拼接写法where uid uid 这条语句就会变成where uid 1 or 11全表数据都会被查出来这就是典型的注入漏洞。4.3 用 TaoToken 验证 SQL 语义如果对某条查询的语义拿不准可以把 SQL 贴到 模型对话 里让模型解释执行计划或者用 ClaudeCodeAnthropic 在本地跑一段脚本验证。接入方式参考 docAPI Key 从 api-keys 取。5. 本篇常见错排查5.1 报错 “DB file not exists”最常见的原因是路径拼错了。getExternalFilesDir(database)返回的是/storage/emulated/0/Android/data/包名/files/database注意中间有个files目录。如果你 adb push 的时候漏了files文件就放错位置了。用adb shell ls逐层确认。5.2 报错 “attempt to write a readonly database”外部存储上的 db 文件权限不对。用 adb push 过去的文件默认属主是 shell应用进程没有写权限。解决办法是 push 之后执行adb shell chmod 666 /sdcard/Android/data/com.example.sqldemo/files/database/mango.db或者干脆在应用内用FileOutputStream拷贝这样文件属主就是应用自己。5.3 版本号不匹配导致 onUpgrade 被反复调用SQLiteOpenHelper构造时传的DATABASE_VERSION必须和外部 db 文件里记录的版本号一致。如果外部 db 是用工具建的默认版本号是 0而你在代码里传了 1第一次打开就会触发onUpgrade把表删了重建。建议建库时就把版本号设成和代码一致或者在onUpgrade里做兼容判断。5.4 查询返回空 Cursor先确认表名和字段名大小写是否一致SQLite 对表名大小写不敏感但字段名敏感。再用cursor.getCount()打印行数如果为 0说明数据没插进去或者 where 条件写错了。可以临时把 SQL 改成select * from user看能不能查到数据。5.5 SQL 注入测试没生效如果你用的是execSQL(sql, bindArgs)或rawQuery(sql, selectionArgs)注入本来就该无效这是正确行为。如果注入生效了说明代码里某处用了字符串拼接全局搜一下 uid 这类写法全部改成占位符。6. 继续深入把外部 db 加载接进你的工程到这里从 SD 卡加载 SQLite 数据库的完整链路就通了清单声明权限、自定义ContextWrapper重写openOrCreateDatabase、启动时拷贝 db 文件、参数化查询防注入、真机验证读取和注入测试。实际项目里我建议把DataBaseContext和SQLiteDBHelper封装成一个DbManager单例避免每次 new Helper 都重新打开文件。如果你在接入过程中遇到路径拼接或权限相关的报错可以到 API Keys 生成一个 Key配合 接入文档 里的示例让模型帮你逐行排查。长期做 Android 编码的话Coding Plan 会更顺手Agent 能直接读你的 DAO 文件给出修改建议。
