更新记录

1.0.1（2026-03-04）

一、文档更新

1.0.0（2026-03-04）

• 支持在应用沙盒内读写、删除文本文件（Android & iOS）

平台兼容性

uni-app(5.01)

uni-app x(5.01)

UTS环境兼容性

hl-app-file

在 应用沙盒（App Sandbox） 内读写文本文件的 UTS 插件，支持 Android 和 iOS。

设计约束

• ✔ 仅访问应用沙盒目录
  • Android：context.filesDir 下的子目录
  • iOS：应用 Documents 目录下的子目录
• ✔ 不访问外部存储（不使用 SD 卡、不使用外部共享目录）
• ✔ 不与其他应用共享文件（文件仅当前应用可见）
• ✔ 所有读写均使用 UTF-8 文本编码

API 说明

插件导入路径：

import {
  writeTextFile,
  readTextFile,
  fileExists,
  deleteFile,
  appendLog
} from '@/uni_modules/hl-app-file'

类型：HlFileWriteOptions

type HlFileWriteOptions = {
  /** 相对路径，例如 "logs/demo.txt" 或 "demo.txt" */
  path: string
  /** 要写入的文本内容（UTF-8） */
  content: string
  /** 是否追加到文件末尾；默认 false（覆盖写入） */
  append?: boolean
}

writeTextFile(options: HlFileWriteOptions): boolean

在应用沙盒中写入一个文本文件。

• 参数
  • options.path：相对路径（禁止以 / 开头）
  • options.content：要写入的文本内容（UTF-8）
  • options.append：是否追加到文件末尾；默认覆盖写入
• 返回值
  • true：写入成功
  • false：写入失败（路径非法、异常等）

readTextFile(path: string): string | null

读取应用沙盒中的文本文件内容。

• 参数
  • path：相对路径
• 返回值
  • string：读取到的文本内容
  • null：文件不存在或读取失败

fileExists(path: string): boolean

判断指定相对路径的文件是否存在。

• 参数
  • path：相对路径
• 返回值
  • true：文件存在
  • false：文件不存在或路径非法

deleteFile(path: string): boolean

删除应用沙盒中的文件。

• 参数
  • path：相对路径
• 返回值
  • true：删除成功，或文件本身就不存在
  • false：删除失败（路径非法或发生异常）

appendLog(path: string, line: string): boolean

在指定文件末尾追加一行日志内容，自动带上时间戳前缀。

• 参数
  • path：相对路径（例如 logs/serial-port.log）
  • line：一行文本内容（函数内部会自动加换行）
• 返回值
  • true：追加成功
  • false：失败（路径非法或异常）

使用示例

import {
  writeTextFile,
  readTextFile,
  fileExists,
  deleteFile,
  appendLog
} from '@/uni_modules/hl-app-file'

// 1. 写入日志文件（覆盖写入）
const ok = writeTextFile({
  path: 'logs/demo.txt',
  content: 'hello sandbox\n',
  append: false
})
console.log('写入结果', ok)

// 2. 追加写入
writeTextFile({
  path: 'logs/demo.txt',
  content: 'append line\n',
  append: true
})

// 3. 读取文件内容
const text = readTextFile('logs/demo.txt')
if (text != null) {
  console.log('文件内容:', text)
}

// 4. 判断文件是否存在
const exists = fileExists('logs/demo.txt')
console.log('文件是否存在:', exists)

// 5. 删除文件
const deleted = deleteFile('logs/demo.txt')
console.log('删除结果:', deleted)

// 6. 追加一行带时间戳的日志（适合串口调试、播放器日志等）
appendLog('logs/serial-port.log', '收到串口数据: 0x01 0x02 0x03')

安全说明与沙盒机制

为了保证应用安全，本插件在 Android 和 iOS 底层均实现了极为严格的“路径锁死”与防穿透保护：

• 强制沙盒根目录匹配：所有传入的相对路径，最终都会被解析到应用的专属物理沙盒内。禁止使用 / 开头的绝对路径尝试越权访问系统分区。
• 防御路径层级逃逸：哪怕在路径中传入恶意的层级跳跃符号（例如 ../../../storage/），原生底层在解析合并完整物理路径后，会再次校验终态绝对路径是否仍然以应用沙盒根目录起头。任何试图跳出沙盒的操作都会被立即拦截阻断并返回失败。
• 自动管理文件夹：在写入文件时（如使用 writeTextFile），只要传入了较深的相对路径（如 cache/data/logs.txt），底层引擎会自动为您递归创建所有缺失的中间文件夹，您不用再专门为此书写创建文件夹的重复代码。
• Android 端 仅锁定位于系统分配的应用内部存储目录（context.filesDir），不读写外部储存卡（SD Card），因此也无需烦人的 Android 存储弹窗权限申请。
• iOS 端 仅锁定位于应用沙盒的 Documents 目录（FileManager.default.urls(for: .documentDirectory...)），绝不会干扰其他 App 的独立容器数据。

常见问题 (FAQ)

Q1：如何清空一个文本文件？ A：如果您只想丢弃文件里现有的文本，但想把文件对象本身继续留在磁盘里，您可以调用 writeTextFile，将 content 传空字符串 "" 且把 append 置为 false，这样文件大小会变成 0 byte（实质上等同于清空重建文件）。

Q2：清空文件和删除文件 (deleteFile) 有什么区别？ A：如上所述，仅仅把空字符盖写进去只是“清空内容”。而调用 deleteFile(path) 才会向系统发出真正的指令，在磁盘文件分配表中把这个文件实体及其索引完全抹除销毁。如果您不需要在业务里留着这个文件，务必使用 deleteFile。