更新记录

1.0.2（2026-03-24）

更新日志

1.0.2 (2026-03-23)

新增

• 支持在打开数据库时通过 dbPath 参数指定自定义文件路径（绝对路径或相对路径）
• 路径不存在时自动创建父目录
• 默认路径保持为应用沙盒 Documents 目录，文件名为 {dbName}.db

优化

• 增强路径解析逻辑，兼容更多格式

1.0.1 (2026-01-20)

新增

• 支持配置加密算法（cipherType）：aes256、aes128、sqlcipher
• 支持配置页面大小（pageSize）
• 支持配置 KDF 迭代次数（kdfIterations）
• 数据库文件格式统一，支持 iOS 与 Android 跨端共用（需使用完全相同的加密参数）

优化

• 加密参数固化到数据库文件，避免重复设置导致异常

1.0.0 (2025-12-30)

初始版本

• 支持打开/创建加密数据库
• 支持关闭数据库连接
• 支持执行非查询 SQL（INSERT、UPDATE、DELETE、CREATE TABLE 等）
• 支持执行查询 SQL（SELECT），返回结果集数组
• 支持事务操作（BEGIN、COMMIT、ROLLBACK）
• 同时支持 iOS 和 Android 平台
• 数据库默认存储在应用沙盒 Documents 目录

平台兼容性

uni-app(3.99)

uni-app x(3.99)

SQLCipher 加密数据库插件

简介

本插件为 uni-app 应用提供基于 SQLCipher 的 SQLite 数据库透明加密支持，使用 256-bit AES 加密算法，保障本地数据安全。插件同时支持 iOS 和 Android 平台，提供简单易用的同步 API，可快速集成到您的项目中。

功能特性

• 全量加密：数据库文件 100% 加密，包括元数据，采用SQLCipher透明加密特性
• 高性能：典型场景下加密开销仅 5%~10%
• 简单易用：提供与标准 SQLite 一致的 API 风格
• 灵活配置：支持自定义加密算法、页面大小、KDF 迭代次数等
• 跨平台：iOS 和 Android 端使用相同的 JS/TS 接口

安装方式

在 HBuilderX 中，打开您的项目，进入 uni_modules 目录。

右键点击空白处，选择“从插件市场导入”，搜索 "yzx-safebase" 加密数据库” 并导入。

或者，直接访问插件市场页面，点击“下载”并按照提示导入。

快速开始

1. 导入插件

   import { openDatabase, executeSql, querySql, transaction, closeDatabase } from '@/uni_modules/yzx-safebase';

2. 打开数据库

   const result = openDatabase({
   dbName: 'mydb',              // 数据库标识（必填）
   password: '123456',          // 加密密码（必填）
   dbPath:'_doc/uniapp_save/',  //存放路径（可选）
   cipherType: 'aes256',        // 加密算法：'aes256'(默认), 'aes128', 'sqlcipher'
   pageSize: 4096,              // 页面大小（可选，默认 4096）
   kdfIterations: 64000         // KDF 迭代次数（可选，默认 64000）
   });
   if (result.code === 0) {
   console.log('数据库打开成功');
   } else {
   console.error('打开失败：', result.errMsg);
   }

3. 创建表

   executeSql({
   sql: `
   CREATE TABLE IF NOT EXISTS user_table (
   _id TEXT PRIMARY KEY NOT NULL,
   name TEXT,
   age INTEGER
   )
   `
   });

4. 插入数据

   const insertRes = executeSql({
   sql: 'INSERT INTO user_table (_id, name, age) VALUES ('111', '张三', 20);'
   });
   if (insertRes.code === 0) {
   console.log('插入成功，影响行数：', insertRes.data.changerow);
   }

5. 查询数据

   const queryRes = querySql({
   sql: 'SELECT * FROM user WHERE age > 10'
   });
   if (queryRes.code === 0) {
   console.log('查询到', queryRes.data.rows.length, '条记录');
   console.log(queryRes.data.rows);
   }

6. 更新数据

   const updateRes = executeSql({
   sql: 'UPDATE user SET age = 30 WHERE name = '张三''
   });
   console.log('更新行数：', updateRes.data.changerow);

7. 删除数据

   const removeRes = executeSql({
   sql: 'DELETE FROM user_table WHERE name = '张三';'
   });
   console.log('删除行数：', updateRes.data.changerow);

8. 事务操作

   //开启事务
   transaction({ operation: 'begin' });
   //提交事务
   transaction({ operation: 'commit' });
   //回滚事务
   transaction({ operation: 'rollback' });

9. 关闭数据库

   closeDatabase();

API 参考

openDatabase(options)

打开或创建加密数据库。

返回值：SafeBaseResult 对象

{
    code: number;       // 0 表示成功，非 0 表示失败
    errMsg: string;     // 错误信息
    data:{
        path:"数据库文件路径"
    }
}

closeDatabase()

关闭数据库连接。

返回值：

{
    code: number;       // 0 表示成功，非 0 表示失败
    errMsg: string;     // 错误信息
    data: null          // 此接口 data 固定为 null
}

executeSql(options)

执行非查询 SQL（如 INSERT、UPDATE、DELETE、CREATE TABLE 等）。

返回值：SafeBaseResult，其中 data 结构为：

{
    code: number;       // 0 表示成功，非 0 表示失败
    errMsg: string;     // 错误信息
    data:{
        changerow: number;      // 受影响的行数
        insertId: number | null;   // 最后插入行的 rowid，若无插入则为 null
    }
}

querySql(options)

执行查询 SQL（SELECT）。

返回值：SafeBaseResult，其中 data 结构为：

{
    code: number;       // 0 表示成功，非 0 表示失败
    errMsg: string;     // 错误信息
    data:{
        rows: any[];               // 查询结果数组，每行是对象
    }
}

transaction(options)

执行事务操作。

返回值：同 openDatabase

{
    code: number;       // 0 表示成功，非 0 表示失败
    errMsg: string;     // 错误信息
    data: null          // 此接口 data 固定为 null
}

注意事项

密码和配置一致性

创建数据库时传入的加密配置（算法、页面大小、KDF 迭代次数）会被固化在数据库文件中，后续打开时必须使用完全相同的配置（至少密码必须正确），否则无法解密。已存在的数据库再次打开时，只需提供密码，无需重复设置配置（若数据库文件需要跨端的话建议显示设置一下配置）。

跨端兼容

若需要在 iOS 和 Android 之间共享同一个加密数据库文件，请确保两端使用完全相同的加密参数（密码、算法、页面大小、KDF 迭代次数等）。

文件路径

• 不传 dbPath 时，数据库文件默认存放在应用沙盒的 Documents 目录下，文件名为 {dbName}.db。
• 若传入相对路径（如 "data/mydb.db"），则相对于 Documents 目录。
• 若传入绝对路径，请确保路径有读写权限。和路径是否存在

性能建议

• 批量操作时使用事务可大幅提升性能。
• 适当调整 pageSize 和 kdfIterations 可在安全性和性能间取得平衡（但需与数据库创建时的设置一致）。

错误处理

所有函数均返回 SafeBaseResult，请务必检查 code 字段，根据 errMsg 进行错误提示或回退操作。

技术支持

如有问题或建议，请在插件评论区留言。