更新记录

1.0.0（2026-10-09）

首个版本。

• 文件转 base64（toBase64 / toBase64Async），支持 dataURL 前缀输出
• base64 转文件（fromBase64 / fromBase64Async），自动剥离 dataURL 前缀与空白字符
• 读图片信息（getInfo / getInfoAsync）
• base64 查图片信息不落盘（infoFromBase64 / infoFromBase64Async）
• 格式转换（convertFormat / convertFormatAsync），jpg / png / webp
• 三端原生实现：Android（Base64 + BitmapFactory）、iOS（NSData + UIImage）、Harmony（Base64Helper + ImagePacker）
• 格式识别按文件内容魔数判定，不依赖扩展名
• webp 在 iOS 与 Harmony 明确降级为 jpg 编码，返回值反映真实格式
• web / 小程序降级到 FileReader + Canvas

平台兼容性

uni-app(3.99)

其他

czg-imgb64 图片与Base64互转

图片与 base64 双向互转，支持 jpg / png / webp 格式转换，自动识别 dataURL 前缀。

平台支持

同步 API 仅 App 端可用（依赖原生同步调用）。web / 小程序请用 *Async 版本。

安装

// App 端
import { toBase64, fromBase64 } from '@/uni_modules/czg-imgb64/index.js'

API

getInfo(path) / getInfoAsync(path)

读图片信息。

const info = getInfo('/path/to/photo.jpg')
// { width: 1920, height: 1080, size: 245678, format: 'jpg' }

format 按文件内容魔数判定，不看扩展名 —— 把 .jpg 改名为 .png 也能正确识别。

toBase64(path, options) / toBase64Async(path, options)

文件转 base64。

const r = toBase64('/path/to/photo.jpg', {
  withPrefix: true,   // 返回 data:image/jpeg;base64,xxxx；默认 false 只给裸 base64
  format: 'png',      // 可选，顺带转格式；不传保持原格式
  quality: 90         // 重编码质量 1~100，仅转格式时用到
})
// { base64: 'data:image/png;base64,...', length: 32891, format: 'png' }

fromBase64(base64, outPath) / fromBase64Async(base64, outPath)

base64 转文件。

const r = fromBase64('data:image/png;base64,iVBORw0...', '/path/to/out.png')
// { path: '/path/to/out.png', size: 12345, width: 800, height: 600, format: 'png' }

• 入参可以带 dataURL 前缀，也可以带换行和空格，插件会自动清理
• outPath 不传时自动生成，落在应用私有目录（不会落到不可写的相对路径）

infoFromBase64(base64) / infoFromBase64Async(base64)

只查信息不落盘。

infoFromBase64('iVBORw0KGgo...')
// { width: 800, height: 600, size: 12345, format: 'png' }

convertFormat(path, format, quality, outPath) / convertFormatAsync(...)

格式转换（落盘）。

const r = convertFormat('/path/to/photo.png', 'jpg', 85, '/path/to/out.jpg')
// { path: '/path/to/out.jpg', size: 88888, width: 1920, height: 1080, format: 'jpg' }

错误处理

所有错误都是抛出的 Error，error.code 给出可判断的错误码：

try {
  const r = toBase64('/not/exist.jpg', {})
} catch (e) {
  if (e.code === 50002) {
    uni.showToast({ title: '读取失败', icon: 'none' })
  }
}

关于 webp

Android 支持 webp 编码，iOS 与 Harmony 无 webp 编码器，传 format: 'webp' 时这两端会明确降级为 jpg 编码，并在返回值的 format 字段里反映真实格式（不会静默给你一个标着 .webp 的 jpg）。

隐私

全部转换在本机完成，不联网、不采集、不上传任何图片或数据。

价格

普通授权版由 DCloud 对 uts 源码加密保护，运行时经云端解密编译；源码授权版提供完整 uts 源码，可自行修改与扩展，同样享受后续版本升级。

隐私说明

本插件全部图片处理在本机完成，不联网、不采集、不上传任何图片或数据。插件不主动读取相册与存储目录，输入完全由调用方通过参数传入。隐私声明详见 package.json 的 dcloudext.declaration。

更新日志

见 changelog.md

开源协议

MIT