UniApp集成SQLite数据库的完整方法步骤

来源：互联网 2026-04-22 19:15:12

一、背景介绍在移动应用开发的世界里，本地数据存储从来都不是一个可选项，而是决定应用体验好坏的关键一环。UniApp作为当下热门的跨平台开发框架，其“一次编写，多端发布”的特性确实诱人。但要让应用真正“活”起来，尤其是在离线状态下，一个高效、可靠的本地数据库就必不可少。这时，SQLite这位轻量级、

一、背景介绍

在移动应用开发的世界里，本地数据存储从来都不是一个可选项，而是决定应用体验好坏的关键一环。UniApp作为当下热门的跨平台开发框架，其“一次编写，多端发布”的特性确实诱人。但要让应用真正“活”起来，尤其是在离线状态下，一个高效、可靠的本地数据库就必不可少。这时，SQLite这位轻量级、嵌入式的关系型数据库老将，就成了绝佳的搭档。

长期稳定更新的攒劲资源： >>>点此立即查看<<<

将UniApp与SQLite结合起来，意味着你的应用获得了强大的本地数据持久化能力。无论是应对网络不稳定的场景，还是需要处理大量结构化的本地数据——比如用户日志、离线缓存、个性化配置——这套组合拳都能游刃有余。

二、核心使用场景

离线应用：网络断了怎么办？有了本地数据库，应用的核心功能依然可以流畅运行，用户体验不打折。
数据缓存：把从服务器获取的数据“暂存”在本地，下次需要时直接读取，既能减少网络请求次数，又能显著提升页面加载速度。
配置管理：用户的个人设置、应用的主题偏好，这些需要持久保存的信息，交给SQLite再合适不过。
日志记录：应用运行过程中产生的各种日志，存储在本地数据库里，排查问题时就能有据可查。
复杂数据存储：当你的数据不再是简单的键值对，而是存在复杂关联关系时，关系型数据库的结构化优势就体现出来了。

三、环境准备与平台支持

3.1 平台支持情况

App（Android/iOS）：这是SQLite的主战场，原生支持，功能完整。
H5：很遗憾，浏览器环境并不直接支持SQLite。通常的替代方案是转向WebSQL或IndexedDB。
小程序：情况有点特殊，需要调用各小程序平台（如微信、支付宝）自家提供的数据库API来实现类似功能。

3.2 插件选择

工欲善其事，必先利其器。在UniApp生态里，有几个成熟的SQLite插件可供选择：

uni-sqlite：官方背书，稳定性有保障，是大多数项目的首选。
se-sqlite：如果你在用UniApp X并青睐UTS开发，这个支持ORM（对象关系映射）的插件能让你的代码更优雅。
lime-sqlite：它的API设计参考了经典的plus.sqlite，对于熟悉那套接口的开发者来说，上手几乎零成本。

四、配置步骤

4.1 安装插件

一切从HBuilderX开始。安装插件的流程非常直观：

打开你的UniApp项目。
在顶部菜单栏找到「工具」，点击进入「插件安装」。
在市场的搜索框里输入“sqlite”，找到「uni-sqlite」插件并安装即可。

4.2 manifest.json 配置

插件装好了，还得告诉打包工具你需要这个功能。打开项目根目录下的manifest.json文件，进行配置。你可以选择直接编辑源码：

{
  "app-plus": {
    "modules": {
      "SQLite": {}
    }
  }
}

或者，更简单的方式是使用图形化界面：

打开manifest.json文件。
切换到「App模块权限配置」标签页。
在长长的功能列表里，找到并勾选上“SQLite（数据库）”。

五、数据库操作封装

5.1 基础数据库操作封装

直接调用原生API虽然可行，但为了代码的整洁和可维护性，封装一层是明智之举。通常在static/sql/目录下创建一个sqllite.js文件，把打开、关闭、查询、执行等操作都包装成Promise函数。

// 数据库名称和路径配置
const sqlName = "mydatabase"
const sqlPath = "_doc/mydatabase.db"

// 打开数据库
function openDb(name, path) {
  return new Promise((resolve, reject) => {
    plus.sqlite.openDatabase({
      name: name,
      path: path,
      success: function(e) {
        console.log('数据库打开成功')
        resolve(e)
      },
      fail: function(e) {
        console.log('数据库打开失败:' + JSON.stringify(e))
        reject(e)
      }
    })
  })
}

// 判断数据库是否打开
function isOpened(name, path) {
  return plus.sqlite.isOpenDatabase({
    name: name,
    path: path
  })
}

// 关闭数据库
function closeDb(name) {
  return new Promise((resolve, reject) => {
    plus.sqlite.closeDatabase({
      name: name,
      success: function(e) {
        console.log('数据库关闭成功')
        resolve(e)
      },
      fail: function(e) {
        console.log('数据库关闭失败')
        reject(e)
      }
    })
  })
}

// 查询SQL（所有查询都用该方法）
function selectSql(name, sqlText) {
  return new Promise((resolve, reject) => {
    plus.sqlite.selectSql({
      name: name,
      sql: sqlText,
      success: function(e) {
        resolve(e)
      },
      fail: function(e) {
        console.log('查询失败:' + sqlText + "-异常信息:" + JSON.stringify(e))
        reject(e)
      }
    })
  })
}

// 执行增删改查都使用该方法
function executeSql(name, sqlText) {
  return new Promise((resolve, reject) => {
    plus.sqlite.executeSql({
      name: name,
      sql: sqlText,
      success: function(e) {
        console.log('操作成功')
        resolve(e)
      },
      fail: function(e) {
        console.log('执行失败:' + sqlText + '-异常信息:' + JSON.stringify(e))
        reject(e)
      }
    })
  })
}

export { sqlName, sqlPath, openDb, isOpened, closeDb, selectSql, executeSql }

5.2 表结构定义

数据库建好了，接下来就是设计表结构。同样，我们可以把建表语句集中管理，比如在tables.js文件中：

import { sqlName, executeSql } from "./sqllite.js"

export function userTable() {
  let createSql = {
    name: "user",
    sql: "id INTEGER PRIMARY KEY AUTOINCREMENT, userId VARCHAR(255) NOT NULL, userName VARCHAR(255) NOT NULL, email VARCHAR(255), createdTime DATETIME DEFAULT CURRENT_TIMESTAMP"
  }
  executeSql(sqlName, `create table if not exists ${createSql.name} (${createSql.sql})`)
}

export function productTable() {
  let createSql = {
    name: "product",
    sql: "id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(255) NOT NULL, price REAL NOT NULL, stock INTEGER DEFAULT 0, category VARCHAR(100)"
  }
  executeSql(sqlName, `create table if not exists ${createSql.name} (${createSql.sql})`)
}

六、应用初始化

万事俱备，只欠东风。我们需要在应用启动时，就完成数据库的初始化和建表工作。这个任务交给App.vue的onLaunch生命周期再合适不过。

import { sqlName, sqlPath, openDb, isOpened } from "./static/sql/sqllite.js"
import { userTable, productTable } from "./static/sql/tables.js"

export default {
  onLaunch() {
    this.initDatabase()
  },
  methods: {
    async initDatabase() {
      try {
        // 判断数据库是否已打开
        let type = isOpened(sqlName, sqlPath)
        if (!type) {
          // 打开数据库
          await openDb(sqlName, sqlPath)
          // 创建表结构
          userTable()
          productTable()
          console.log('数据库初始化完成')
        }
      } catch (error) {
        console.error('数据库初始化失败:', error)
      }
    }
  }
}

七、CRUD 操作示例

7.1 数据操作封装

基础框架搭好了，现在来实现具体的业务逻辑。以用户管理为例，我们可以在user.js中封装一套完整的增删改查方法。

import { sqlName, selectSql, executeSql } from "./sqllite.js"
const name = sqlName

// 查询所有用户
export function getAllUsers() {
  let sql = "SELECT * FROM user ORDER BY createdTime DESC"
  return selectSql(name, sql)
}

// 根据ID查询用户
export function getUserById(id) {
  let sql = `SELECT * FROM user WHERE id = ${id}`
  return selectSql(name, sql)
}

// 添加用户
export function addUser(userData) {
  let sql = `INSERT INTO user (userId, userName, email) VALUES ('${userData.userId}', '${userData.userName}', '${userData.email}')`
  return executeSql(name, sql)
}

// 更新用户
export function updateUser(id, userData) {
  let sql = `UPDATE user SET userName = '${userData.userName}', email = '${userData.email}' WHERE id = ${id}`
  return executeSql(name, sql)
}

// 删除用户
export function deleteUser(id) {
  let sql = `DELETE FROM user WHERE id = ${id}`
  return executeSql(name, sql)
}

7.2 在页面中使用

封装好的方法，在Vue组件里调用起来就非常清晰了。下面是一个简单的用户列表页面示例：

import { getAllUsers, addUser, updateUser, deleteUser } from "@/static/sql/user.js"

export default {
  data() {
    return {
      users: [],
      newUser: {
        userId: '',
        userName: '',
        email: ''
      }
    }
  },
  async onLoad() {
    await this.loadUsers()
  },
  methods: {
    async loadUsers() {
      try {
        const result = await getAllUsers()
        this.users = result
      } catch (error) {
        console.error('加载用户失败:', error)
        uni.showToast({
          title: '加载失败',
          icon: 'none'
        })
      }
    },
    async handleAddUser() {
      if (!this.newUser.userName || !this.newUser.userId) {
        uni.showToast({
          title: '请填写完整信息',
          icon: 'none'
        })
        return
      }
      try {
        await addUser(this.newUser)
        uni.showToast({
          title: '添加成功',
          icon: 'success'
        })
        this.newUser = { userId: '', userName: '', email: '' }
        await this.loadUsers()
      } catch (error) {
        console.error('添加用户失败:', error)
        uni.showToast({
          title: '添加失败',
          icon: 'none'
        })
      }
    },
    async handleDeleteUser(id) {
      try {
        await deleteUser(id)
        uni.showToast({
          title: '删除成功',
          icon: 'success'
        })
        await this.loadUsers()
      } catch (error) {
        console.error('删除用户失败:', error)
        uni.showToast({
          title: '删除失败',
          icon: 'none'
        })
      }
    }
  }
}

八、高级功能

8.1 事务处理

当需要执行一系列数据库操作，并且要求它们要么全部成功，要么全部失败时，事务（Transaction）就派上用场了。这在批量插入或更新时尤为重要，能确保数据的一致性。

export const batchInsert = (table, dataArray) => {
  plus.sqlite.transaction({
    name: dbName,
    operation: async () => {
      for (const data of dataArray) {
        await insertData(table, data)
      }
    }
  })
}

8.2 索引优化

随着数据量增长，查询速度可能会变慢。这时，为经常用于查询条件的字段（比如用户名）创建索引，是提升性能最有效的手段之一。

plus.sqlite.executeSql({
  name: dbName,
  sql: "CREATE INDEX IF NOT EXISTS idx_user_name ON user(userName)"
})

8.3 条件查询封装

为了避免在业务代码中拼接复杂的SQL字符串，可以封装一个通用的条件查询方法，让查询变得更简洁、更安全。

export const selectWithConditions = (table, conditions = {}) => {
  let sql = `SELECT * FROM ${table}`
  const keys = Object.keys(conditions)
  if (keys.length > 0) {
    sql += ' WHERE '
    sql += keys.map(key => `${key} = '${conditions[key]}'`).join(' AND ')
  }
  return selectSql(dbName, sql)
}

九、性能优化策略

索引优化：再次强调，对高频查询字段建立索引，这是性价比最高的优化。
批量操作：尽可能使用事务进行批量插入或更新，减少单次IO操作的开销。
路径优化：在Android 10及以上版本，使用_doc/目录存储数据库文件，可以避免一些棘手的存储权限问题。
连接管理：避免在短时间频繁打开和关闭数据库连接，保持连接复用。
查询优化：养成好习惯，避免使用SELECT *，只查询你真正需要的字段。

十、跨平台兼容方案

10.1 条件编译处理

UniApp的条件编译特性，在这里成了解决跨平台差异的神器。你可以让代码在App端使用SQLite，在H5端则自动切换为模拟实现。

// #ifdef APP-PLUS
import { openDb } from './db/sqlite'
// #endif

// #ifdef H5
const openDb = () => Promise.resolve(mockDb)
// #endif

10.2 H5 环境模拟

为了在浏览器中也能进行开发和调试，我们可以用一个内存对象来模拟数据库的基本操作。

const mockDb = {
  users: [],
  executeSql: (sql) => {
    if (sql.includes("INSERT")) {
      const name = sql.match(/VALUES\s*\('(.*)'\)/)[1]
      mockDb.users.push({ name })
    }
    return Promise.resolve()
  }
}

十一、调试与维护

11.1 数据库可视化

导出数据库：开发时，可以通过ADB命令将设备上的数据库文件导出到电脑。
查看工具：导出的.db文件，可以用像“DB Browser for SQLite”这样的图形化工具打开，直观地查看和修改数据，调试效率倍增。

11.2 错误处理

健壮的应用离不开完善的错误处理。将数据库操作包裹在统一的错误处理逻辑中，是个好实践。

async function safeDatabaseOperation(operation) {
  try {
    return await operation()
  } catch (error) {
    console.error('数据库操作失败:', error)
    // 记录错误日志
    // 根据错误类型进行相应处理
    throw error
  }
}