更新记录

1.1.9（2026-10-14）

• 新增可选 Promise 接口：打开、关闭、参数化读写、结构化 CRUD 和批处理可使用 async / await；原有回调接口继续保留，失败返回原有 SqliteFail。
• 新增 executeMany / executeManyAsync，同一 SQL 模板绑定多组参数，写入前整批校验，默认整批事务；Android、iOS 一次准备重复执行，支持汇总和逐条摘要。Harmony 支持 API 12 的批量更新/删除，插入使用原 batchAsync；Web、小程序按基础 SQL 子集降级。
• 新增默认关闭的操作耗时与慢操作摘要，可配置 1–500 条缓存；摘要不记录库名、SQL、参数或数据，getDiagnostics 返回独立快照，clearDiagnostics 同时清空。
• 修复 iOS 蒸汽模式下查询记录字段丢失、Promise 失败无法读取错误码及回滚详情的问题；保持原有调用方式。
• 修复 iOS 批量写入未传事务选项时未按默认值回滚，以及 null 参数被拒绝的问题；保留显式关闭事务后的部分成功语义。
• 修复 iOS 显式传入 true/false 事务选项被误拒，以及首次迁移时空版本记录被误判为无效整数的问题。
• 修复当前 Android 编译器下原生错误属性初始化及结构化 CRUD 转交参数缺少明确类型的问题，保留原调用方式和业务语义。
• 修复完整示例在 Web 中导入 App 专属系统另存为接口的问题；App 保留原文件备份恢复流程，其他端提示使用 JSON 导入导出。
• 修复演示页面自检标题对比度不足、快捷按钮文字被截断的问题。
• 完善 uni-app、uni-app x 完整示例及内置组件，新增独立示例库的 500 条导入、异步查询、增改删体验、诊断开关和结果展示，统一两套完整页面的模块顺序、按钮分组和日志区；README 按业务模块提供最小示例、参数与平台范围。
• 本版本尚未发布。原有调用无需修改；App 使用包含当前插件原生代码的自定义基座或重新打包，不能只更新 WGT；Web 和小程序重新编译即可。

1.1.8（2026-09-20）

• 新增与 lizhao-choose-file 联动的 uni-app、uni-app x 示例和说明，可将沙盒数据库备份另存到系统文件位置，也可把系统备份复制到沙盒后恢复；SQLite 公共调用方式不变。
• 修复 uni-app 示例把 Android、iOS 恢复流程写成无效条件编译，导致恢复前未关闭数据库、恢复后未重新打开的问题；统一使用 APP-PLUS，无需修改调用代码。
• 修复 Android 正常关闭数据库后遗留的 PERSIST 回滚日志被误判为数据库仍在占用的问题；只清理目标库头部已清零的失效 journal，WAL、SHM、有效回滚日志和源备份伴随文件仍会拒绝，避免覆盖活跃数据库。
• 优化 README 的介绍、功能特色、适用场景、示例位置、模块教程、API 查询资料和常见问题顺序，方便从最小接入逐步查阅完整能力。
• 本版本尚未发布。升级后无需修改调用代码或项目配置；Android 原生文件恢复逻辑已变化，需要重新制作并安装 Android 自定义基座或重新打包，不能仅更新 WGT。iOS、Harmony、Web 和小程序无需因本次修复重新制作原生包。

1.1.7（2026-09-19）

• 修复 iOS 更新和删除未设置筛选条件时可能被错误放行的问题；全表操作仍须显式传入 allowAll: true。
• 修复 iOS 使用 WAL 模式后，关闭数据库再恢复备份仍可能提示日志文件占用的问题；保留未关闭连接及文件占用保护。
• 修复 iOS 云打包时关闭数据库失败提示无法正常生成的问题；升级后无需修改调用代码。
• 本版本尚未发布。升级后无需修改调用代码或项目配置；iOS、Android 需要重新原生联编，或重新制作并安装对应平台自定义基座/正式包，不能仅更新 WGT；Web 重新编译即可。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

其他

lizhao-sqlite-pro

介绍

lizhao-sqlite-pro 是面向 uni-app / uni-app x 的本地数据库插件。App 端使用各平台原生 SQLite 能力，业务代码可以同时使用参数化 SQL、结构化增删改查、Schema Builder、轻量 ORM、迁移、备份恢复和诊断功能。

功能特色

• 在 App 中保存离线订单、表单草稿、巡检记录、消息、文章和业务配置。
• 使用 ? 占位符绑定数据，减少手动拼接 SQL 带来的错误和注入风险。
• 可选 Promise 接口顺序完成读写，同模板批量写入默认整批事务。
• 按需查看操作耗时与慢操作摘要，默认关闭采集。
• 不想手写完整 SQL 时，使用对象配置完成查询、新增、更新和删除。
• 在应用升级时按版本执行数据库迁移，避免重复执行同一批变更。
• 创建并核对表、字段和索引，完成 Upsert、计数、聚合和分页。
• 备份、恢复或导出本地数据，并通过数据库健康检查和诊断信息排查问题。
• 配合 lizhao-choose-file 把沙盒备份保存到系统文件位置，或把用户选择的备份复制回沙盒后恢复。
• 在 Web、微信小程序和支付宝小程序中保留统一入口，并按真实能力明确降级。

本插件管理的是当前应用沙盒内的本地数据，不提供云端同步、账号间自动合并或服务器数据库能力。数据库文件不提供整库加密；敏感字段应由业务在写入前加密，整库加密需要另行接入 SQLCipher 等方案并安全管理密钥。

适合哪些场景

• 离线订单、巡检、仓储、工单等需要在无网络环境下持续读写的数据。
• 表单草稿、文章、消息、本地统计和应用配置等需要可靠持久化的数据。
• 数据表需要随 App 版本升级，并要求迁移只执行一次的项目。
• 希望用结构化 CRUD、Schema Builder 或 ORM Lite 减少手写 SQL 的业务。
• 需要备份、恢复、换机归档，或与 lizhao-choose-file 联动访问系统文件位置的场景。
• 同一套业务还要运行在 Web 或小程序，并接受明确能力降级的跨端项目。

先选择接入方式

如果没有既有数据库封装，建议按“模块一 → 模块二 → 模块三”的顺序阅读。只有确实需要升级结构、文件备份或问题排查时，再继续后面的模块。

下载与导入

1. 从 DCloud 插件市场将插件导入项目。
2. 页面和业务代码只从插件根目录导入，不要直接引用 utssdk 内部文件。
3. App 端需要完成原生联编，并使用包含当前插件的自定义基座或正式安装包。

uni-app 导入

// 普通 uni-app 页面从插件根目录导入需要的 API。
import {
  openDatabase,
  executePrepared,
  closeDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

uni-app x 导入

// <script setup lang="uts"> 中同样只从插件根目录导入。
import {
  openDatabase,
  executePrepared,
  closeDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

UTS 插件通过 HBuilderX 编译后直接 import 使用，不通过 uni.xxx 或 uni.requireNativePlugin 调用。后续业务示例以普通 uni-app 写法为主；uni-app x 使用同名 API，强类型页面示例见文末“完整示例”。

示例位置

• uni-app 完整页面：uni_modules/lizhao-sqlite-pro/example/uniapp/sqlitePro.vue
• uni-app x 完整页面：uni_modules/lizhao-sqlite-pro/example/uniappx/index.uvue
• uni-app 内置组件：uni_modules/lizhao-sqlite-pro/components/lizhao-sqlite-pro/lizhao-sqlite-pro.vue
• uni-app x 内置组件：uni_modules/lizhao-sqlite-pro/components/lizhao-sqlite-pro/lizhao-sqlite-pro.uvue

第一次接入建议先运行完整示例并完成“模块一”，确认打开、建表、写入、查询和关闭链路正常，再按业务需要继续后续模块。

从基础到进阶：按业务模块使用

除模块七的能力判断外，后续示例都假设数据库名称保持一致，并且相关操作只在 openDatabase 成功后执行。

模块一：打开数据库并完成第一次读写

适合第一次接入。下面示例会打开数据库、创建表、写入一条数据、查询结果，最后关闭连接。

import {
  openDatabase,
  executePrepared,
  closeDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'

// 查询结束后再关闭连接，避免异步操作尚未完成就提前关闭数据库。
function closeDemoDatabase() {
  closeDatabase({
    name: databaseName,
    fail(err) {
      console.error('关闭数据库失败', err)
    }
  })
}

function queryFirstUser() {
  executePrepared({
    name: databaseName,
    sql: 'SELECT id, name, score FROM users WHERE id = ?',
    params: [1],
    query: true,
    success(rows) {
      console.log('查询结果', rows)
    },
    fail(err) {
      console.error('查询失败', err)
    },
    complete() {
      closeDemoDatabase()
    }
  })
}

function writeFirstUser() {
  executePrepared({
    name: databaseName,
    sql: 'INSERT OR REPLACE INTO users (id, name, score) VALUES (?, ?, ?)',
    params: [1, '小李', 95],
    query: false,
    success() {
      queryFirstUser()
    },
    fail(err) {
      console.error('写入失败', err)
      closeDemoDatabase()
    }
  })
}

function createUserTable() {
  executePrepared({
    name: databaseName,
    sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, score REAL DEFAULT 0)',
    params: [],
    query: false,
    success() {
      writeFirstUser()
    },
    fail(err) {
      console.error('建表失败', err)
      closeDemoDatabase()
    }
  })
}

openDatabase({
  name: databaseName,
  success(res) {
    console.log('数据库已打开', res.path)
    createUserTable()
  },
  fail(err) {
    console.error('打开数据库失败', err)
  }
})

executePrepared 中的 ? 会按 params 顺序绑定。写入值、查询条件和用户输入都建议使用参数绑定，不要直接拼进 SQL 字符串。query: true 表示成功回调返回行数组；建表、插入、更新和删除使用 query: false。

同一个业务流程应始终使用相同的 name。连接可以在页面或数据服务初始化时打开，在不再有待执行操作时关闭；不要在发起查询后立即调用 closeDatabase。Web 和小程序调用 closeDatabase 时会同时清空该名称下的内存数据，再次打开得到空库。

模块二：使用对象配置完成增删改查

适合希望减少 SQL 拼接的业务。以下方法仍会对数据值做参数绑定，表名和字段名则会经过标识符校验。

import {
  insertRow,
  selectRows,
  updateRows,
  deleteRows,
  batchCrud
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'

// 新增一行。
export function addUser() {
  insertRow({
    name: databaseName,
    table: 'users',
    values: [
      { column: 'name', value: '小王' },
      { column: 'score', value: 88 }
    ],
    success(res) {
      console.log('新增成功，行号', res.insertId)
    },
    fail(err) {
      console.error('新增失败', err)
    }
  })
}

// 查询分数不低于 80 的用户。
export function loadHighScoreUsers() {
  selectRows({
    name: databaseName,
    table: 'users',
    columns: ['id', 'name', 'score'],
    where: [{ column: 'score', op: '>=', value: 80 }],
    orderBy: [{ column: 'score', direction: 'DESC' }],
    limit: 20,
    offset: 0,
    success(rows) {
      console.log('高分用户', rows)
    },
    fail(err) {
      console.error('查询失败', err)
    }
  })
}

// 按主键更新，where 仍然使用参数绑定。
export function renameUser(userId, newName) {
  updateRows({
    name: databaseName,
    table: 'users',
    values: [{ column: 'name', value: newName }],
    where: 'id = ?',
    whereParams: [userId],
    fail(err) {
      console.error('更新失败', err)
    }
  })
}

// 按主键删除。
export function removeUser(userId) {
  deleteRows({
    name: databaseName,
    table: 'users',
    where: [{ column: 'id', op: '=', value: userId }],
    fail(err) {
      console.error('删除失败', err)
    }
  })
}

// 一次完成多项结构化操作，默认使用事务并在失败时回滚。
export function addAndQueryUser() {
  batchCrud({
    name: databaseName,
    items: [
      {
        action: 'insert',
        table: 'users',
        values: [
          { column: 'name', value: '小周' },
          { column: 'score', value: 92 }
        ]
      },
      {
        action: 'select',
        table: 'users',
        where: [{ column: 'score', op: '>=', value: 90 }],
        orderBy: [{ column: 'id', direction: 'DESC' }]
      }
    ],
    transaction: true,
    rollbackOnFail: true,
    success(res) {
      console.log('批量结构化操作结果', res.results)
    },
    fail(err) {
      console.error('批量结构化操作失败', err)
    }
  })
}

对象条件支持 = / != / > / >= / < / <= / LIKE / IN / BETWEEN / IS NULL / IS NOT NULL。LIKE 的 % 由调用方放入值中；IN 和 BETWEEN 使用 values 数组。

updateRows 和 deleteRows 没有 where 时会被安全拦截。只有明确要操作整张表时才传 allowAll: true，并建议在业务层再次确认。

Web 支持结构化 CRUD，但普通 selectRows 暂不执行 groupBy / having；需要 Web 聚合时请使用模块三的 aggregateRows。微信和支付宝小程序不支持结构化 CRUD，应先查看模块七。

模块三：用 Schema Builder 和 ORM Lite 管理数据模型

适合需要统一建表、核对结构，以及完成 Upsert、计数、聚合和分页的项目。

import {
  ensureSchema,
  upsertRow,
  countRows,
  aggregateRows,
  paginateRows
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'

ensureSchema({
  name: databaseName,
  tables: [{
    name: 'members',
    columns: [
      { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
      { name: 'email', type: 'TEXT', notNull: true, unique: true },
      { name: 'score', type: 'REAL', defaultValue: 0 },
      { name: 'created_at', type: 'TEXT', defaultExpression: 'CURRENT_TIMESTAMP' }
    ],
    indexes: [
      { name: 'idx_members_score', columns: ['score'], unique: false }
    ]
  }],
  success(schemaResult) {
    console.log('结构已就绪', schemaResult)

    upsertRow({
      name: databaseName,
      table: 'members',
      values: [
        { column: 'email', value: 'demo@example.com' },
        { column: 'score', value: 96 }
      ],
      conflictColumns: ['email'],
      success(upsertResult) {
        console.log('是否新增', upsertResult.inserted)
        console.log('是否更新', upsertResult.updated)
      },
      fail(err) {
        console.error('Upsert 失败', err)
      }
    })
  },
  fail(err) {
    console.error('Schema 创建或核对失败', err)
  }
})

countRows({
  name: databaseName,
  table: 'members',
  where: [{ column: 'score', op: '>=', value: 60 }],
  success(res) {
    console.log('及格人数', res.count)
  }
})

aggregateRows({
  name: databaseName,
  table: 'members',
  aggregates: [
    { function: 'COUNT', column: '*', alias: 'member_count' },
    { function: 'AVG', column: 'score', alias: 'average_score' }
  ],
  success(rows) {
    console.log('统计结果', rows)
  }
})

paginateRows({
  name: databaseName,
  table: 'members',
  columns: ['id', 'email', 'score'],
  orderBy: [{ column: 'id', direction: 'DESC' }],
  page: 1,
  pageSize: 20,
  success(res) {
    console.log('总数', res.total)
    console.log('当前页', res.rows)
  }
})

ensureSchema 只创建缺失的表和索引，并核对已有字段、主键、非空和索引声明。发现现有结构与声明冲突时会失败，不会自动删表、改列或重建业务数据。应用升级时需要新增字段或搬迁数据，请使用模块五的 runMigrations。

upsertRow 的 conflictColumns 必须对应主键或唯一约束，否则底层数据库会返回真实错误。聚合函数只允许 COUNT / SUM / AVG / MIN / MAX；分页页码从 1 开始，每页最多 500 条。

需要单独管理索引时，可使用 createIndex 和 dropIndex。索引名称、表名和字段名都会经过校验。

模块四：使用事务和批处理保证一组操作

适合 App 原生端的订单与明细、主记录与日志等必须一起成功的写入流程。普通批量 SQL 优先使用 batch，它默认开启事务并在任一条失败时回滚。

import { batch } from '@/uni_modules/lizhao-sqlite-pro'

batch({
  name: 'business',
  items: [
    {
      sql: 'INSERT INTO orders (order_no, amount) VALUES (?, ?)',
      params: ['ORDER-1001', 299]
    },
    {
      sql: 'INSERT INTO order_logs (order_no, action) VALUES (?, ?)',
      params: ['ORDER-1001', 'created']
    }
  ],
  transaction: true,
  rollbackOnFail: true,
  success(res) {
    console.log('全部执行成功', res.count)
  },
  fail(err) {
    console.error('批处理失败，请通过 err.details 确认执行位置和回滚结果', err)
  }
})

只有操作之间需要业务判断时，才手动控制 begin / commit / rollback：

import {
  transaction,
  executePrepared
} from '@/uni_modules/lizhao-sqlite-pro'

function rollbackOrder() {
  transaction({
    name: 'business',
    operation: 'rollback',
    fail(err) {
      console.error('回滚失败', err)
    }
  })
}

function createOrderInTransaction() {
  transaction({
    name: 'business',
    operation: 'begin',
    success() {
      executePrepared({
        name: 'business',
        sql: 'INSERT INTO orders (order_no, amount) VALUES (?, ?)',
        params: ['ORDER-1002', 199],
        success() {
          transaction({
            name: 'business',
            operation: 'commit',
            fail(err) {
              console.error('提交失败', err)
              rollbackOrder()
            }
          })
        },
        fail(err) {
          console.error('写入失败', err)
          rollbackOrder()
        }
      })
    },
    fail(err) {
      console.error('开启事务失败', err)
    }
  })
}

开启手动事务后，每条失败路径都应明确回滚；不要在事务尚未提交或回滚时关闭数据库。batchCrud 也支持相同的 transaction 和 rollbackOnFail 配置。

已经开启手动事务时，批处理请传 transaction: false，由你在外层统一提交或回滚；默认批处理不会接管已有事务。批次 SQL 中不要夹带 BEGIN / COMMIT / ROLLBACK / SAVEPOINT 等事务命令。

如果允许保留失败前的成功项，可传 rollbackOnFail: false：批处理会停止后续条目，并尝试提交本次事务中已经成功的部分，但仍进入 fail。不要把失败前的执行数量直接当作最终保存数量，具体判断见后部“批处理失败详情”。

Web 和小程序支持当前内存会话的事务快照：回滚会恢复本次事务之前的表和数据，但不会把数据保存到磁盘。涉及订单、余额等必须原子落盘的数据，只应在 nativeSqlite: true 且 persistent: true 的 App 原生端使用本模块；其他平台应改用服务端事务或平台自己的持久化方案。

模块五：用迁移安全升级数据库结构

适合应用升级时新增表、索引、字段或修正已有数据。App 原生端会在迁移记录表中保存结果，每个正整数版本只执行一次。

import { runMigrations } from '@/uni_modules/lizhao-sqlite-pro'

runMigrations({
  name: 'business',
  migrations: [
    {
      version: 1,
      name: '创建设置表',
      sql: [
        'CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT)'
      ]
    },
    {
      version: 2,
      name: '给用户表增加状态字段',
      sql: [
        "ALTER TABLE users ADD COLUMN status TEXT DEFAULT 'active'"
      ]
    }
  ],
  success(res) {
    console.log('迁移前版本', res.fromVersion)
    console.log('迁移后版本', res.toVersion)
    console.log('本次执行版本', res.appliedVersions)
  },
  fail(err) {
    console.error('迁移失败', err)
  }
})

迁移数组应按版本递增维护。已经发布并在设备上执行过的迁移不要改写，应新增更高版本；否则不同安装时间的设备可能得到不同结构。App 原生端默认记录表名为 lizhao_sqlite_schema_migrations，一般无需修改。

插件会先校验整份迁移，再按版本从小到大执行高于当前最大版本的项。每个版本的 SQL 和版本记录一起提交；某个版本失败时会回滚该版本并停止后续迁移，之前已成功提交的版本保留。迁移前先结束手动事务，SQL 中不要自行开启、提交或回滚事务。

Web 和小程序会在同一次数据库打开期间记住迁移记录；重复调用时只执行高于已应用最大版本的项，不会重放旧迁移。记录按 tableName 隔离，关闭数据库或刷新页面后仍会丢失。降级端只适合演示和轻量内存数据，不应承担正式数据库升级。

迁移中的 SQL 是结构脚本，没有独立 params 字段。涉及业务输入的数据修正应先严格校验，或在迁移完成后通过参数化 API 执行。

模块六：备份、恢复、导出和导入数据

适合换机、故障备份、调试和小规模跨端数据搬迁。App 原生端可做数据库文件备份；JSON 导出导入在 App、Web 和小程序都可以按各自能力使用。

importDatabase 不是增量合并：导入 JSON 时会重建导出内容涉及的表，降级端也会重建当前内存数据。执行前请先备份，并确认导入内容可以覆盖目标表。

import {
  getDatabasePath,
  backupDatabase,
  restoreDatabase,
  exportDatabase,
  importDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'
const backupPath = getDatabasePath(databaseName) + '.bak'

// App 原生端备份真实数据库文件。
export function createDatabaseBackup() {
  backupDatabase({
    name: databaseName,
    path: backupPath,
    success(res) {
      console.log('备份文件', res.targetPath)
    },
    fail(err) {
      console.error('备份失败', err)
    }
  })
}

// 从同一备份文件恢复。Android/iOS 请先完成操作并 closeDatabase，再调用此函数。
// Harmony 则保持数据库打开。恢复成功后按下方平台表继续操作。
export function restoreDatabaseBackup() {
  restoreDatabase({
    name: databaseName,
    path: backupPath,
    success(res) {
      console.log('恢复成功', res.success)
    },
    fail(err) {
      console.error('恢复失败', err)
    }
  })
}

// 导出稳定 JSON；可保存到业务文件，也可直接交给 importDatabase。
export function exportDatabaseJson() {
  exportDatabase({
    name: databaseName,
    success(res) {
      console.log('导出表数量', res.tableCount)
      console.log('导出 JSON', res.data)
    },
    fail(err) {
      console.error('导出失败', err)
    }
  })
}

export function importDatabaseJson(jsonText) {
  importDatabase({
    name: databaseName,
    data: jsonText,
    success(res) {
      console.log('导入表数量', res.tableCount)
    },
    fail(err) {
      console.error('导入失败', err)
    }
  })
}

backupDatabase / restoreDatabase 需要真实数据库文件，Web 和小程序会返回不支持。exportDatabase 返回包含 schema / tables / rows 的 lizhao-sqlite-pro-json 文本，可直接作为 importDatabase({ data }) 的输入。

联动 lizhao-choose-file 访问系统文件位置

SQLite 原生备份与恢复只操作应用沙盒普通路径。Android 文件选择器返回的 content://、iOS 安全作用域 URL、Harmony picker URI 都是系统授权标识，不等于 SQLite 可直接打开的本地路径。

• 备份：先调用 backupDatabase 生成沙盒备份，成功后把 targetPath 交给 saveSandboxFile。
• 恢复：先调用 pickFileToSandbox，等待文件完整复制，再把返回的 file.path 交给 restoreDatabase。

import {
  backupDatabase,
  restoreDatabase,
  getDatabasePath
} from '@/uni_modules/lizhao-sqlite-pro'
import {
  pickFileToSandbox,
  saveSandboxFile
} from '@/uni_modules/lizhao-choose-file'

const databaseName = 'business'
const sandboxBackupPath = getDatabasePath(databaseName) + '.system-backup.db'

export function backupAndSaveToSystem() {
  backupDatabase({
    name: databaseName,
    path: sandboxBackupPath,
    success(backupResult) {
      // 只有数据库备份成功后，才打开系统另存为界面。
      saveSandboxFile({
        path: backupResult.targetPath,
        filename: databaseName + '-backup.db',
        mimeType: 'application/vnd.sqlite3',
        success(saveResult) {
          console.log('已保存', saveResult.name, saveResult.size)
        },
        fail(err) {
          console.error('系统另存为失败', err)
        }
      })
    },
    fail(err) {
      console.error('数据库备份失败', err)
    }
  })
}

export function pickBackupAndRestore() {
  pickFileToSandbox({
    accept: '.db,.sqlite,.sqlite3,.bak',
    directory: 'cache',
    success(file) {
      // file.path 已是应用沙盒普通路径，不要传原始系统 URI。
      restoreDatabase({
        name: databaseName,
        path: file.path,
        success() {
          console.log('数据库恢复成功')
        },
        fail(err) {
          console.error('数据库恢复失败', err)
        }
      })
    },
    fail(err) {
      console.error('选择或复制备份失败', err)
    }
  })
}

Android/iOS 恢复前必须关闭目标数据库，恢复成功后重新 openDatabase；Harmony 则保持数据库打开后调用恢复。两个插件的 uni-app 与 uni-app x 示例页都提供“备份并另存为”和“选择备份并恢复”按钮，可直接查看完整连接处理。

saveSandboxFile.success.targetUri 只表示本次系统保存目标，不保证是 SQLite 可用或可长期访问的路径。后续要恢复该文件时仍应重新调用 pickFileToSandbox。文件桥只支持 Android、iOS、Harmony；Web 和小程序请使用 JSON 导出导入或平台自己的文件方案。

跨端 JSON 导入建议只传 data。path 在各 App 平台的处理方式不同，数据库文件恢复请统一使用 restoreDatabase，不要把 importDatabase({ path }) 当作跨端恢复接口。Android 和 iOS 不会替你关闭连接，尚未关闭时恢复会返回失败；成功后再次调用 openDatabase，使用自定义路径时仍传入原来的 path。

JSON 适合调试、迁移和小规模数据搬迁；数据量较大时，App 端优先使用文件备份。导出内容可能包含业务数据，保存、上传或提交给技术支持前应自行脱敏和加密。

模块七：按平台能力处理 Web 和小程序降级

适合同一套业务代码需要运行到多个平台的项目。先读取能力，再决定显示完整功能、使用基础 SQL，还是给出不支持提示。

import {
  getCapabilities,
  executePrepared,
  selectRows
} from '@/uni_modules/lizhao-sqlite-pro'

const capabilities = getCapabilities()

console.log('当前平台', capabilities.platform)
console.log('是否真实 SQLite', capabilities.nativeSqlite)
console.log('数据是否持久化', capabilities.persistent)

if (capabilities.structuredCrud) {
  selectRows({
    name: 'business',
    table: 'users',
    success(rows) {
      console.log('结构化查询结果', rows)
    },
    fail(err) {
      console.error('结构化查询失败', err)
    }
  })
} else if (capabilities.parameterized) {
  executePrepared({
    name: 'business',
    sql: 'SELECT * FROM users',
    params: [],
    query: true,
    success(rows) {
      console.log('基础 SQL 查询结果', rows)
    },
    fail(err) {
      console.error('基础 SQL 查询失败', err)
    }
  })
} else {
  console.log(capabilities.reason || '当前平台不支持本地数据库能力')
}

能力字段：

Web 页面刷新或调用 closeDatabase 后，内存数据会丢失，不要把它当成浏览器持久化数据库。微信和支付宝小程序关闭数据库时同样会清空当前内存数据。小程序的结构化 CRUD、Schema Builder、Upsert、聚合和分页会明确进入失败回调；这类业务应使用基础 SQL 子集，或改用平台自己的持久化能力。

Web 基础 SQL 支持建表、DROP TABLE [IF EXISTS]、插入，以及带基础 WHERE 条件的查询和删除；查询支持按字段 ORDER BY 排序和非负整数 LIMIT / OFFSET 分页。字符串条件支持 ? 参数、数字、单引号文本、NULL 判断和 AND / OR；文本中的单引号写成两个单引号，例如 'O''Brien'。函数、子查询等超出此子集的表达式会返回错误，不能按完整 SQLite 语法使用。

模块八：上线前检查数据库并收集诊断

适合接入完成后的自检，以及排查“表不存在、数据为空、文件过大、平台能力不一致”等问题。

import {
  configureDatabase,
  inspectDatabase,
  runHealthCheck,
  getCapabilities,
  getDiagnostics,
  clearDiagnostics
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'
const capabilities = getCapabilities()

// 只有能力矩阵确认支持时才配置真实 PRAGMA。
if (capabilities.pragmaConfig) {
  configureDatabase({
    name: databaseName,
    foreignKeys: true,
    journalMode: 'WAL',
    busyTimeoutMs: 3000,
    synchronous: 'NORMAL',
    fail(err) {
      console.error('数据库配置失败', err)
    }
  })
}

inspectDatabase({
  name: databaseName,
  includeSampleRows: false,
  sampleLimit: 3,
  success(res) {
    console.log('表数量', res.tableCount)
    console.log('结构摘要', res.tables)
  },
  fail(err) {
    console.error('结构检查失败', err)
  }
})

runHealthCheck({
  name: databaseName,
  fullCheck: false,
  includeTableStats: true,
  success(res) {
    console.log('数据库是否健康', res.ok)
    console.log('提示信息', res.warnings)
  },
  fail(err) {
    console.error('健康检查失败', err)
  }
})

const diagnostics = getDiagnostics({ includeLogs: true })
console.log('运行平台', diagnostics.platform)
console.log('已打开数据库', diagnostics.openedDatabases)
console.log('最近诊断', diagnostics.logs)

// 问题排查结束后可清空旧日志。
clearDiagnostics()

getDiagnostics() 直接同步返回结果，也支持可选的 success / complete 回调，回调收到同一次调用的诊断快照。iOS 回调会异步派发，不要依赖回调在函数返回前执行；只读取返回值的现有写法仍可使用。clearDiagnostics() 同步清空当前插件日志。

includeSampleRows: true 会把少量样例数据放入结构检查结果。诊断或工单场景若不需要真实内容，应保持 false；复制日志、导出 JSON 或结构样例前都应检查是否包含敏感信息。

fullCheck: false 使用较轻量的检查，适合日常检查；完整一致性检查开销更高，建议在维护页面或用户主动触发时使用。

模块九：用 Promise 顺序完成读写

需要依次打开、建表、写入再查询时，可以使用可选的异步接口，让执行顺序直接体现在代码里。原有回调接口继续可用；两种方式返回相同业务结果，异步失败以原有的 SqliteFail 拒绝。

下面的流程使用独立演示库，App、Web 和基础 SQL 小程序降级端均可调用：

import { openDatabaseAsync, executePreparedAsync, closeDatabaseAsync } from '@/uni_modules/lizhao-sqlite-pro'

async function saveAndRead() {
  const name = 'async_demo'
  await openDatabaseAsync({ name })
  try {
    await executePreparedAsync({ name, sql: 'CREATE TABLE IF NOT EXISTS notes (id INTEGER, title TEXT)' })
    await executePreparedAsync({ name, sql: 'INSERT INTO notes (id, title) VALUES (?, ?)', params: [1, '离线笔记'] })
    const rows = await executePreparedAsync({ name, sql: 'SELECT id, title FROM notes', query: true })
    console.log(rows)
  } finally {
    await closeDatabaseAsync({ name })
  }
}

结构化操作在 App 和 Web 中使用 selectRowsAsync、insertRowAsync、updateRowsAsync、deleteRowsAsync；参数沿用对应回调接口，但不传 success / fail / complete。更新、删除仍保留无条件操作保护，明确全表操作时才设置 allowAll: true。小程序不支持的结构化能力仍返回 9040013。

import { openDatabaseAsync, executePreparedAsync, updateRowsAsync, selectRowsAsync, closeDatabaseAsync } from '@/uni_modules/lizhao-sqlite-pro'

async function renameAndRead() {
  const name = 'crud_async_demo'
  await openDatabaseAsync({ name })
  try {
    await executePreparedAsync({ name, sql: 'CREATE TABLE IF NOT EXISTS notes (id INTEGER, title TEXT)' })
    await executePreparedAsync({ name, sql: 'INSERT INTO notes (id, title) VALUES (?, ?)', params: [1, '待修改'] })
    await updateRowsAsync({ name, table: 'notes', values: [{ column: 'title', value: '新标题' }], where: 'id = ?', whereParams: [1] })
    return await selectRowsAsync({ name, table: 'notes', where: 'id = ?', whereParams: [1] })
  } finally {
    await closeDatabaseAsync({ name })
  }
}

Promise 只改变接入方式，不表示自动在后台线程执行。同一个库的读写按 await 顺序调用；不要并发执行依赖同一事务的操作。batchAsync 沿用 batch 的事务、rollbackOnFail 和失败详情规则。

模块十：用一条模板导入多条数据

导入离线订单、同步记录或初始化数据时，使用 executeMany / executeManyAsync 提交一条写入 SQL 和多组参数。Android、iOS 在一次调用中复用原生语句，减少逐条准备和回调；其他端按支持范围执行。

下面先准备独立演示库，再导入三条笔记。Harmony 的插入请使用 batchAsync，其他平台可运行此基础模板：

import { openDatabaseAsync, executePreparedAsync, executeManyAsync, closeDatabaseAsync } from '@/uni_modules/lizhao-sqlite-pro'

async function importNotes() {
  const name = 'many_demo'
  await openDatabaseAsync({ name })
  try {
    await executePreparedAsync({ name, sql: 'CREATE TABLE IF NOT EXISTS notes (id INTEGER, title TEXT)' })
    const result = await executeManyAsync({
      name,
      sql: 'INSERT INTO notes (id, title) VALUES (?, ?)',
      parameterSets: [[101, '第一条'], [102, '第二条'], [103, '第三条']]
    })
    console.log('执行条目', result.count, '影响行数', result.affectedRows)
  } finally {
    await closeDatabaseAsync({ name })
  }
}

默认以事务执行整批：一条失败就回滚本批次。已有手动事务时，传 transaction: false 并自行提交或回滚；该模式不会接管调用方事务，若没有外部事务，失败前的成功条目可能已经保存。参数在任何写入前整批校验并复制，后面的参数组不合法时不会留下成功前缀。

不接受多语句、查询、建表、RETURNING、编号或命名占位符、OR ROLLBACK，以及对象、数组、undefined、NaN、Infinity 等参数值。需要混合 SQL、查询结果或逐条不同模板时继续使用 batch / batchAsync。

summary 模式的 results 为空数组；items 模式每条只包含执行摘要，不返回 SQL 文本，insertId 固定为 -1，表示本接口不提供生成主键。count 是成功执行的参数组数量，affectedRows 是实际受影响行数；执行成功但没有匹配记录的语句也计入 count。

失败沿用 SqliteFail；在 catch 或 fail 中读取 errCode、errMsg 和 details，无需解析错误文本。details 提供 failedIndex（从 0 起，无法对应条目时为 -1）、completedCount、rolledBack、phase。completedCount 记录失败前执行数量，不代表已经提交；rolledBack 为 null 时不能认定已回滚。阶段包括 validate、begin、execute、finalize、commit、rollback。

回调方式在数据库已打开、notes 表已创建时使用：

import { executeMany } from '@/uni_modules/lizhao-sqlite-pro'

executeMany({
  name: 'demo', sql: 'INSERT INTO notes (id, title) VALUES (?, ?)',
  parameterSets: [[201, '待同步']], resultMode: 'items',
  success: (result) => console.log(result.count, result.results),
  fail: (error) => console.log(error.errCode, error.details),
  complete: () => console.log('本次导入已结束')
})

模块十一：查看操作耗时和慢操作

排查导入或查询响应慢时，显式开启摘要采集，再运行需要观察的操作。默认不采集；只记录新 Promise 接口和 executeMany 的操作名称、时间、成功状态、条数和错误码，不记录库名、SQL、参数、结果行。

import { openDatabaseAsync, executePreparedAsync, closeDatabaseAsync, configureDiagnostics, getDiagnostics, clearDiagnostics } from '@/uni_modules/lizhao-sqlite-pro'

async function inspectQueryTime() {
  const name = 'diagnostic_demo'
  await openDatabaseAsync({ name })
  try {
    await executePreparedAsync({ name, sql: 'CREATE TABLE IF NOT EXISTS notes (id INTEGER, title TEXT)' })
    configureDiagnostics({ enabled: true, slowThresholdMs: 50, maxEntries: 30 })
    await executePreparedAsync({ name, sql: 'SELECT id, title FROM notes', query: true })
    const snapshot = getDiagnostics({ includeLogs: false })
    console.log(snapshot.operations)
  } finally {
    configureDiagnostics({ enabled: false })
    clearDiagnostics()
    await closeDatabaseAsync({ name })
  }
}

configureDiagnostics 返回 boolean；配置不合法返回 false，并保留原配置。关闭采集后仍可读取已有摘要，clearDiagnostics 同时清空原日志和操作摘要。耗时包含 API 内部执行与等候，排除使用者回调时间；不是 SQLite 执行计划或独立引擎耗时。executeManyAsync 只记录一次 executeMany。

常用 API 与配置

API 用途总览

异步接入与批量诊断

通用回调

大部分异步 API 都支持以下回调：

success 和 fail 只会走其中一个，complete 用于收尾。不要只监听 complete 判断成功；应在 success 中更新成功状态，在 fail 中展示错误。

getCapabilities()、getDiagnostics()、getDatabasePath() 和 clearDiagnostics() 以同步返回或同步执行为主。isOpenDatabase() 同步返回 boolean，并会通过传入的回调返回状态详情。

数据库连接参数

适用于 openDatabase / isOpenDatabase / closeDatabase：

getDatabasePath(name) 直接返回路径字符串。降级平台的路径只用于保持接口一致，不代表存在可复制的 SQLite 文件。

原始 SQL、参数化 SQL 与事务参数

App 端多条 SQL 不建议用分号拼成一个字符串；请使用 SQL 数组、batch 或显式事务。动态值优先使用 executePrepared，表名和字段名不能用 ? 绑定。

Android 参数绑定保留 null、数字和字符串的区别，布尔值按 1 / 0 保存；例如 null 不会被改成空字符串。WITH 开头的写入也按写入返回摘要，查询返回行数组。每个批次或迁移数组元素只放一条 SQL；一个完整的触发器定义算一条语句。

结构化 CRUD 参数

对象式条件项：

对象排序项写作 { column, direction }，其中 column 必填，direction 默认 ASC，可选 ASC / DESC。

结构化 values / where / orderBy 使用上表的固定字段数组，不支持任意对象动态键。例如写入姓名应传 values: [{ column: 'name', value: '小明' }]，不要传 values: { name: '小明' }；这样可以保持各 App 平台的调用方式一致。

batchCrud.items[] 额外包含必填的 action，可选值为 select / insert / update / delete；并可按动作使用 columns / values / where / whereParams / groupBy / having / havingParams / orderBy / limit / offset / allowAll。

Schema Builder 与 ORM Lite 参数

ensureSchema 的核心字段：

索引和 ORM Lite 特有字段：

上述 where / whereParams / orderBy 的写法与结构化 CRUD 使用同一规则；countRows 只有筛选条件，不包含排序和分页参数。

迁移、文件与维护参数

支持平台

App 端使用真实数据库文件。Web 使用内存降级，小程序使用更小的基础 SQL 子集。对明确不支持的能力，降级端会进入 fail / complete，不伪造成功。降级端事务仅保证当前内存会话的提交和回滚，不提供持久化；迁移记录也不会跨关闭或刷新保留。configureDatabase 的兼容结果不代表真实 SQLite PRAGMA 已生效。跨端项目应先调用 getCapabilities()，不要只根据插件市场的平台标记推断能力。

主要返回值

查询类 API 直接在 success 中返回行数组；其他常用结果如下：

失败回调统一收到 SqliteFail，常用字段为 errSubject / errCode / errMsg / details。Web 和小程序中的普通错误对象不继承 UniError，但仍保留这些字段，业务代码可以统一读取 err.errCode 和 err.errMsg。

Android 的 executeSql / executePrepared 写入摘要中，affectedRows 是该语句实际影响的行数，结构操作为 0。executeSql 传数组时，行数和行号描述最后一条语句，statementCount 为执行条数。只有能确认本次新增行时才返回 insertId，否则为 -1；更新、无 rowid 表、UPSERT 更新或行号未变化时，不应把它当成新的业务主键。

批处理失败详情

batch / batchCrud 失败时，可读取 err.details 定位进度；不改变原来的 errCode / errMsg 处理方式。

当 rolledBack 为 null 时，不要直接重试整批写入；先检查连接状态和实际数据，避免重复保存。transaction: false 时，外层事务是否提交或回滚仍由调用方决定。

错误码

完整示例

两套完整页面使用相同的模块顺序和操作分组：功能介绍 → 离线数据流程 → 快速验证 → 辅助操作与文件备份恢复 → 全量自检 → 当前状态与日志 → 完整能力面板。对应按钮、配色和尺寸保持一致。

完整页面和内置组件提供“批量导入与异步查询”面板：显式准备独立示例库、导入 500 条、查询前 5 条，并在支持结构化操作的平台体验异步增改删。演示行在成功后清理，面板展示结果数量与耗时。诊断由开关启用，普通打开不写入数据；原有快速上手、ORM、App 系统文件备份恢复和全量自检继续保留。

插件内置两套完整示例和同名 easycom 组件：

• uni-app 页面：example/uniapp/sqlitePro.vue
• uni-app x 页面：example/uniappx/index.uvue
• uni-app 组件：components/lizhao-sqlite-pro/lizhao-sqlite-pro.vue
• uni-app x 组件：components/lizhao-sqlite-pro/lizhao-sqlite-pro.uvue

直接使用内置组件

<template>
  <!-- easycom 会按项目类型选择 .vue 或 .uvue 组件。 -->
  <lizhao-sqlite-pro />
</template>

组件包含打开、写入、查询、事务、结构化 CRUD、Schema、ORM Lite、迁移、文件操作和诊断按钮，适合先验证项目是否正确接入。正式业务仍建议在自己的数据服务中按需导入 API。

uni-app x 强类型页面示例

<template>
  <view>
    <button @click="openAndQuery">打开并查询数据库</button>
  </view>
</template>

<script setup lang="uts">
import {
  openDatabase,
  executePrepared,
  closeDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName: string = 'business'

// UTS 页面中先定义函数，再交给按钮和回调使用。
function closeCurrentDatabase(): void {
  closeDatabase({
    name: databaseName,
    fail(err) {
      console.log('关闭失败', err)
    }
  })
}

function queryUsers(): void {
  executePrepared({
    name: databaseName,
    sql: 'SELECT * FROM users ORDER BY id DESC',
    params: [] as Array<any>,
    query: true,
    success(rows: any) {
      console.log('uni-app x 查询结果', rows)
    },
    fail(err) {
      console.log('uni-app x 查询失败', err)
    },
    complete() {
      closeCurrentDatabase()
    }
  })
}

function openAndQuery(): void {
  openDatabase({
    name: databaseName,
    success() {
      queryUsers()
    },
    fail(err) {
      console.log('uni-app x 打开失败', err)
    }
  })
}
</script>

一键全量自检

内置 uni-app / uni-app x 组件和完整示例提供“一键全量自检”，会从插件根入口串行调用真实公开 API，并生成“通过 / 失败 / 跳过 / 耗时”报告。

• 手动检查：进入完整示例，点击“一键全量自检”，结束后可复制安全报告。
• 自动检查：仅在明确的测试场景给完整示例页追加 autoFullCheck=1；日志会输出稳定的 START、ITEM、DONE 和 FAILED 标记。
• 普通打开示例不会自动执行，也不会自动创建或写入自检数据库。
• skipped 表示当前平台能力矩阵明确不支持，不等于通过。
• App 结果必须来自包含当前插件代码的匹配安装包；旧基座中的历史结果不能证明新源码已运行。

注意事项

• 所有数据库操作都应在 openDatabase.success 后执行，并在最后一个异步操作完成后再关闭连接。
• 动态数据使用 executePrepared 或结构化 API 绑定，不要直接拼接用户输入。
• updateRows / deleteRows 默认禁止无条件整表操作；allowAll: true 只用于明确且经过确认的场景。
• ensureSchema 只创建和核对，不自动改列或删除数据；发布后的结构升级使用新的迁移版本。
• App 端多条 SQL 使用数组、batch 或事务，不要依赖分号拼接多条命令。
• Web 和小程序属于内存降级，不可当作完整、持久化的 SQLite 文件数据库；调用 closeDatabase 会清空同名数据和迁移记录，事务快照只在当前内存会话内有效。
• Web 普通结构化查询暂不支持 groupBy / having；Web 聚合使用 aggregateRows。
• 小程序不支持结构化 CRUD 与 ORM Lite；受限能力会触发 fail / complete，不会伪造成功。
• 文件备份恢复只适用于具有真实数据库文件的 App 平台；Android/iOS 恢复前须关闭源库、目标库及其所有别名连接，恢复成功后重新打开。跨端搬迁可使用 JSON 导出导入。
• Android/iOS 备份路径不能与原库、原库的伴随文件或其他已打开数据库相同；备份前先提交或回滚当前事务。遇到数据库忙或并发写入提示时，暂停写入后重试，不会继续复制不完整的数据。
• Android/iOS 恢复请使用完整且已关闭的 SQLite 备份文件，操作期间不能由其他线程或进程读写源文件和目标文件。源备份存在 WAL、SHM 或 journal 时始终拒绝；目标库存在 WAL、SHM 或活跃 journal 时也会拒绝。Android 正常关闭后，PERSIST 模式可能仅把 journal 头部清零，文件后部仍保留旧页内容；插件会在原子替换前识别并清理这种失效 journal，无需手动删除。临时文件写入或校验失败不会覆盖原目标。
• Android/iOS 在当前进程内记住已打开过的自定义路径，便于关闭后恢复；应用重启后请先按原 path 打开并关闭数据库，再执行恢复，不能仅凭数据库名称找回自定义路径。
• JSON 导入会重建涉及的表，执行前必须确认允许覆盖并先做好备份；跨端调用优先传 data。
• 导出 JSON、样例行和诊断日志可能包含业务信息，对外提供前应检查、脱敏并安全传输。
• 当前数据库文件没有内置整库加密。敏感字段或整库加密方案需要由项目另行设计，并安全保存密钥。
• App Android、iOS 和 Harmony 使用原生能力时，需要制作并安装包含插件的自定义基座或正式包；只更新 WGT 不会替换已编译的 UTS 原生代码。

常见问题

调用后提示数据库未打开

按以下顺序检查：

1. 后续操作是否写在 openDatabase.success 之后。
2. openDatabase 和查询、写入使用的 name 是否完全一致。
3. 是否在异步 SQL 完成前调用了 closeDatabase。
4. 页面切换或业务服务销毁时是否提前关闭了共享连接。

查询成功但返回空数组

空数组表示查询执行成功，但没有符合条件的数据。请确认目标表确实有数据、事务已经提交、字段名正确，并检查 where 与 whereParams 数量是否对应。调试时可以先去掉条件，再逐项恢复。

为什么参数写进 SQL 后容易报错

姓名、搜索词、时间和其他动态值不要直接拼接。请使用：

executePrepared({
  name: 'business',
  sql: 'SELECT * FROM users WHERE name = ?',
  params: ['小李'],
  query: true,
  fail(err) {
    console.error('查询失败', err)
  }
})

? 只能绑定数据值，不能替代表名、字段名、排序方向或 SQL 关键字。这些结构项可改用结构化 API，并使用固定白名单。

Web 刷新后数据为什么消失

Web 使用内存数据库降级，persistent 为 false，页面刷新、运行上下文重建或调用 closeDatabase 后数据都不会保留。这一实现用于跨端演示、轻量缓存和接口连通；需要浏览器持久化时应使用 IndexedDB、服务端存储或其他适合 Web 的方案。

小程序为什么提示结构化 CRUD 或 ORM Lite 不支持

微信和支付宝小程序当前只实现基础内存 SQL 子集，不支持 selectRows / insertRow / updateRows / deleteRows / batchCrud，也不支持 Schema Builder、Upsert、聚合和分页。请先判断 getCapabilities()，使用 executePrepared / selectSql 的受支持子集，或采用小程序自己的持久化方案。

ensureSchema 为什么报告结构冲突

ensureSchema 不会自动修改已有字段，以免意外破坏数据。当字段类型、主键、非空或索引声明与现有数据库不一致时，它会返回 9040015。应编写更高版本的 runMigrations 显式完成结构变更。

更新或删除整表为什么被拒绝

这是默认安全保护。请优先提供 where；只有业务确实需要操作整表时才传 allowAll: true。建议在界面和业务服务层同时增加确认，避免误删数据。

备份恢复和 JSON 导出导入怎么选择

• App 原生端、数据量大、同平台恢复：优先 backupDatabase / restoreDatabase。
• 跨端、小规模搬迁、调试或人工查看：使用 exportDatabase / importDatabase。
• Web 或小程序没有真实 SQLite 文件，只能使用 JSON 能力或平台自己的存储。

JSON 导入会重建导出内容涉及的表，不是按主键增量合并。导入前先备份目标数据，并优先把导出的文本通过 data 传入；不要同时传 data 和 path。

为什么不能把系统选择器返回的 URI 直接传给恢复接口

content://、iOS 安全作用域 URL 和 Harmony picker URI 依赖系统临时授权，既不是跨平台普通路径，也可能在回调结束后失效。请使用 lizhao-choose-file.pickFileToSandbox 先复制到当前应用沙盒，再把返回的 file.path 交给 restoreDatabase。直接截取、拼接或把 URI 转成看似本地的字符串都不可靠。

Android 正常关闭后为什么还会看到 .db-journal

Android SQLite 可能使用 PERSIST 模式保留回滚日志：提交后 journal 头部清零，文件后部仍可保留上一次事务的旧页内容。插件会在恢复目标库前识别并清理这种失效 journal；如果检测到 WAL、SHM、有效回滚日志，或源备份本身带有伴随文件，仍会返回占用错误。不要手动删除无法确认状态的数据库日志文件。

数据库文件是否已经加密

没有。插件市场的源码保护、应用沙盒访问控制和数据库文件加密是三件不同的事。当前插件未内置 SQLCipher、PRAGMA key 或等价整库密钥配置；如果攻击者在越权设备环境中取得数据库及 WAL 文件，未额外加密的数据可能被读取。

敏感数据可在写入前做字段级加密。需要整库加密时，应另行实现加密数据库并把密钥保存在 Android Keystore、iOS Keychain 或 Harmony HUKS 等安全设施中，不要把固定密钥写在代码或配置文件里。

App 接入后如何使用当前插件能力

App 请安装包含当前插件原生代码的自定义基座或正式包，单独更新页面资源不能增加原生能力；Web 重新编译页面资源后即可使用。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。