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

一、背景介绍

在移动应用开发中，本地数据存储是至关重要的功能。uniapp 作为一款跨平台开发框架，支持一次编写代码发布到多个平台（ios、android、h5、小程序等）。而 sqlite 是一款轻量级的嵌入式关系型数据库，具有高效、可靠和安全的特点。

将 uniapp 与 sqlite 结合，可以实现本地数据的持久化存储，特别适合在离线状态下的数据操作需求，以及需要存储大量结构化数据的应用场景，如日志记录、离线缓存、本地配置管理等。

二、核心使用场景

离线应用：在没有网络连接的情况下，应用仍能正常使用本地数据
数据缓存：缓存服务器数据，减少网络请求，提升用户体验
配置管理：存储用户设置、应用配置等持久化数据
日志记录：记录应用运行日志，便于问题排查
复杂数据存储：需要关系型数据库支持的复杂数据结构存储

三、环境准备与平台支持

3.1 平台支持情况

app（android/ios）：完全支持 sqlite 数据库
h5：不支持 sqlite，需使用 websql 或 indexeddb 替代
小程序：部分支持，需使用小程序自带的数据库 api

3.2 插件选择

推荐使用以下插件之一：

uni-sqlite：官方推荐的 sqlite 插件
se-sqlite：基于 uniapp x + uts 开发的本地数据库操作插件，支持 orm 面向对象的模型化开发方式
lime-sqlite：参考 plus.sqlite api 实现的 sqlite uts api 组件

四、配置步骤

4.1 安装插件

在 hbuilderx 中安装 sqlite 插件：

打开 hbuilderx，进入项目
点击菜单「工具」->「插件安装」
搜索「sqlite」，安装「uni-sqlite」插件

4.2 manifest.json 配置

在项目的 manifest.json 文件中配置 sqlite 权限：

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

或者通过图形化界面配置：

打开 manifest.json
进入「app模块权限配置」
勾选 sqlite（数据库）选项

五、数据库操作封装

5.1 基础数据库操作封装

创建 static/sql/sqllite.js 文件进行统一管理：

// 数据库名称和路径配置
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 表结构定义

创建 static/sql/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 中初始化数据库：

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 数据操作封装

创建 static/sql/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 事务处理

批量操作时使用事务保证数据一致性：

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 条件查询封装

封装通用的条件查询方法：

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 条件编译处理

使用 uni-app 的条件编译区分平台：

// #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 browser for sqlite 等工具查看数据库内容

11.2 错误处理

完善的错误处理机制：

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

十二、最佳实践建议

合理设计数据模型：根据应用需求设计合理的数据表结构
数据加密：敏感数据应进行加密存储
版本管理：实现数据库版本升级机制
备份恢复：提供数据备份和恢复功能
性能监控：监控数据库操作性能，及时发现性能瓶颈

总结

uniapp 集成 sqlite 数据库为移动应用提供了强大的本地数据存储能力。通过本文介绍的完整流程，你可以实现从环境配置到高级功能的全面数据库集成。在实际开发中，应根据具体应用场景选择合适的技术方案，并遵循最佳实践，确保数据操作的性能、安全性和稳定性。

记住，良好的数据库设计和管理是应用成功的关键因素之一。合理利用 sqlite 的特性，可以为用户提供流畅的离线体验和高效的数据管理功能。

到此这篇关于uniapp集成sqlite数据库的文章就介绍到这了,更多相关uniapp集成sqlite数据库内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

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

2026年04月20日 • uniapp •我要评论