芒里偷闲应用媒体
数据管理
应用安全
设备管理
Ability (程序框架)
用户选了工作区,怎样重启后仍能读写?
Z通过 DocumentViewPicker 选到的目录 URI 只有临时读写权限,应用退出或设备重启后权限自动清除,光把路径存下来是不够的——下次拿这个 URI 去访问时,授权已经没了。
解决思路分两步:先把临时权限持久化,每次启动再激活。
第一步,选完目录后立刻调用 fileShare.persistPermission 把权限持久化,同时把 URI 存到本地(比如用 preferences)。
第二步,应用每次启动时,从本地读出 URI,调用 fileShare.activatePermission 激活已持久化的权限,之后就能正常读写。
前置条件:需要在 module.json5 声明 ohos.permission.FILE_ACCESS_PERSIST 权限,并用 canIUse 确认设备支持 SystemCapability.FileManagement.AppFileService.FolderAuthorization。
完整代码如下:
import { BusinessError } from '@kit.BasicServicesKit'
import { picker } from '@kit.CoreFileKit'
import { fileShare } from '@kit.CoreFileKit'
import { preferences } from '@kit.ArkData'
const PREF_NAME: string = 'workspace_pref'
const KEY_URI: string = 'workspace_uri'
async function selectAndPersistWorkspace(context: Context): Promise<string> {
let documentSelectOptions = new picker.DocumentSelectOptions()
let documentPicker = new picker.DocumentViewPicker()
let uris: Array<string> = await documentPicker.select(documentSelectOptions)
let policyInfo: fileShare.PolicyInfo = {
uri: uris[0],
operationMode: fileShare.OperationMode.READ_MODE | fileShare.OperationMode.WRITE_MODE
}
let policies: Array<fileShare.PolicyInfo> = [policyInfo]
await fileShare.persistPermission(policies)
let pref: preferences.Preferences = await preferences.getPreferences(context, PREF_NAME)
await pref.put(KEY_URI, uris[0])
await pref.flush()
return uris[0]
}
async function activateWorkspace(context: Context): Promise<string> {
let pref: preferences.Preferences = await preferences.getPreferences(context, PREF_NAME)
let uri: string = pref.getSync(KEY_URI, '') as string
if (uri.length === 0) {
return ''
}
let policyInfo: fileShare.PolicyInfo = {
uri: uri,
operationMode: fileShare.OperationMode.READ_MODE | fileShare.OperationMode.WRITE_MODE
}
let policies: Array<fileShare.PolicyInfo> = [policyInfo]
await fileShare.activatePermission(policies)
return uri
}
module.json5 中需要加:
"requestPermissions": [
{
"name": "ohos.permission.FILE_ACCESS_PERSIST"
}
]
几个注意点:
- 只能对已获取的临时权限做持久化,不能拿一个没授权过的 URI 直接 persistPermission,否则会报错。
- 持久化数据存在系统数据库里,但每次启动不会自动加载到内存,必须手动 activatePermission 激活才能用。
- 应用卸载后持久化授权会清除(API 24 起可在 module.json5 的 metadata 配置 ohos.fileshare.supportPreservePersistentPermission 标签来保留)。
橙动创意保存目录字符串不等于保存访问授权,重启后没有权限时,先检查使用的 URI 是否支持持久化、选择时是否取得所需读写权限,以及持久化结果有没有成功。不同 URI 来源和设备形态可能有不同限制,不能对任意沙箱外路径直接恢复权限。
请补 DocumentViewPicker 的选择方式、目标设备/API 和 persist/activate 的返回结果。支持的目录应保存 URI 并按对应授权流程恢复;不支持持久化时,要让用户重新选择或改用应用沙箱,不能只记绝对路径后反复重试写入。
卢队长FilePicker 授权“重启即丢”的原因:Picker 返回的 URI 只具备临时读写权限,临时授权在应用退出或设备重启后清除,所以把 URI 字符串存进 Preferences、下次冷启动直接 openSync,会被拒绝并报 13900001(Operation not permitted)。
建议方案:在临时授权有效期内调用 persistPermission 把授权写入系统持久化记录,冷启动时用 activatePermission 把历史授权重新加载到当前进程。但需要申请权限:需要 ohos.permission.FILE_ACCESS_PERSIST 权限(受限开放权限,需 ACL 申请)、文件夹授权仅平板和电脑生效、手机端需按单文件持久化或数据内化降级。
飞b6结论:在 HarmonyOS 中,用户通过文件选择器选中了目录,并不代表应用永久获得了该目录的读写权限。
保存目录路径或 URI,只是保存了资源的位置,并没有保存访问授权。因此应用重启后可能出现 Permission denied、13900001 等错误。
推荐方案是:FilePicker 获取目录 URI → fileShare 持久化授权 → Preferences 保存 URI → 重启后激活授权并验证 → 继续读写。
一、为什么重启后会丢失权限?
核心原因是 HarmonyOS 使用沙箱隔离和基于 URI 的文件授权机制。
| 操作 | 能否保证重启后访问 |
|---|---|
| 保存目录绝对路径 | 不能 |
| 保存 FilePicker 返回的 URI | 不能,仅保存标识 |
| 使用临时 URI 授权 | 不能保证 |
|
| 满足条件时可以持久化 |
| 重启后 | 激活此前持久化的权限 |
其中 fileShare.persistPermission() 从 API 11 开始支持,需要声明 ohos.permission.FILE_ACCESS_PERSIST。具体还取决于目录 URI 是否支持持久授权以及设备能力。
二、推荐实现流程

三、ArkTS 实现持久化目录授权
先在 module.json5 中声明:
{
"requestPermissions": [
{
"name": "ohos.permission.FILE_ACCESS_PERSIST"
}
]
}然后封装工作区权限管理类。这里假设已经通过支持目录选择的 Picker 获取到了 folderUri。
import { fileShare } from '@kit.CoreFileKit';
export class WorkspacePermission {
private static getPolicy(
folderUri: string
): fileShare.PolicyInfo[] {
return [{
uri: folderUri,
operationMode:
fileShare.OperationMode.READ_MODE |
fileShare.OperationMode.WRITE_MODE
}];
}
// 用户首次选择目录后调用
static async persist(folderUri: string): Promise<void> {
const policies = this.getPolicy(folderUri);
await fileShare.persistPermission(policies);
await fileShare.activatePermission(policies);
}
// 应用重启时调用
static async restore(folderUri: string): Promise<boolean> {
const policies = this.getPolicy(folderUri);
try {
const result =
await fileShare.checkPersistentPermission(policies);
if (!result[0]) {
return false;
}
await fileShare.activatePermission(policies);
return true;
} catch (error) {
console.error(`恢复工作区权限失败: ${JSON.stringify(error)}`);
return false;
}
}
}使用方式:
// 首次选择目录
await WorkspacePermission.persist(folderUri);
// 授权成功后,用 Preferences 保存 folderUri
// 应用重启
const hasPermission =
await WorkspacePermission.restore(savedFolderUri);
if (hasPermission) {
// 继续验证实际目录的读取、写入能力
} else {
// 引导用户重新选择工作区
}注意:checkPersistentPermission() 返回 true 表示持久授权存在,不代表目录没有被移动、删除,也不保证文件提供方仍允许实际读写。还需进行一次真实访问测试。
四、如果仍然提示无权限,重点排查这些情况
| 错误或现象 | 可能原因 | 处理建议 |
|---|---|---|
|
| 没有获得接口所需权限 | 检查权限声明及系统版本限制 |
|
| 当前设备不支持 | 判断设备能力,使用兼容方案 |
|
| URI 不允许持久化、模式无效等 | 检查错误详情和 URI 来源 |
|
| 未成功持久化授权 | 重新通过 Picker 获取授权 |
| 重启后能读取但不能写入 | 只持久化了读权限 | 检查 |
| 授权成功但访问失败 | 目录已不存在、被移动或访问方式不正确 | 验证 URI 和实际文件操作 |
另外,并不是所有 HarmonyOS 设备都支持自由选择任意目录。 例如部分 HarmonyOS 6 手机不支持与 PC 一样的 DocumentSelectMode.FOLDER 目录选择方式,因此要根据手机、平板、PC 的实际能力做兼容处理。
五、工作区工具推荐的兼容方案
如果开发的是 Markdown 编辑器、代码编辑器、文档管理器等需要长期访问文件目录的应用,建议提供两种工作模式:
模式 A:外部工作区(支持目录授权的设备)
用户选择工作区 → 持久授权 → 保存 URI → 下次启动恢复授权 → 继续读写。
模式 B:应用内部工作区(无法持久授权的设备)
用户通过 Picker 导入文件 → 复制到应用沙箱 → 在沙箱内长期编辑 → 用户主动选择导出或保存回外部位置。
模式 B 不依赖长期持有外部目录权限,因此更容易兼容不同设备。缺点是需要自行管理导入副本与原文件之间的同步、冲突和导出关系。
最终建议: 不要将“保存工作区路径”当成“保存工作区权限”。正确做法是持久化 URI 授权,并在每次冷启动后验证、激活权限。对于不支持目录长期授权的设备,使用沙箱工作区作为降级方案,比反复申请权限更可靠。
官方参考:fileShare 持久化授权接口 | 获取并使用公共目录。
仙银
根因就一句话:通过 Picker 选文件或目录拿到的 URI 权限是临时的,应用退出就没了。光保存路径没用,权限没跟着路径一起留下来。
官方文档写得很清楚:临时授权在应用退出后或设备重启后会清除。想让权限活过重启,得做两件事——先持久化授权,再在下次启动时激活。
具体做法分三步:
- 用 Picker 选完目录后,立刻调
fileShare.persistPermission()把临时权限持久化,同时把 URI 存到 Preferences 里 - 下次启动时,从 Preferences 读出之前存的 URI,调
fileShare.activatePermission()激活权限 - 激活成功后就能正常读写了
注意:persistPermission 和 activatePermission 都需要声明 ohos.permission.FILE_ACCESS_PERSIST 权限(module.json5 里配),而且设备要支持 SystemCapability.FileManagement.AppFileService.FolderAuthorization 这个系统能力。
完整最小示例:
import { picker, fileShare } from '@kit.CoreFileKit';
import { preferences } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';
let dataPreferences: preferences.Preferences | null = null;
async function initPreferences(context: Context) {
dataPreferences = await preferences.getPreferences(context, 'workdir_prefs');
}
async function selectAndPersistWorkDir() {
const folderPicker = new picker.FolderViewPicker();
let uris: Array<string> = await folderPicker.select();
if (uris.length === 0) {
return;
}
let policyInfo: fileShare.PolicyInfo = {
uri: uris[0],
operationMode: fileShare.OperationMode.READ_MODE | fileShare.OperationMode.WRITE_MODE,
};
let policies: Array<fileShare.PolicyInfo> = [policyInfo];
await fileShare.persistPermission(policies)
.then(async () => {
if (dataPreferences) {
await dataPreferences.put('workdir_uri', uris[0]);
await dataPreferences.flush();
}
})
.catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
console.error(`persistPermission failed: ${err.message}`);
});
}
async function activateWorkDirOnStartup() {
if (!dataPreferences) {
return;
}
let savedUri: string = dataPreferences.getSync('workdir_uri', '') as string;
if (!savedUri) {
return;
}
let policyInfo: fileShare.PolicyInfo = {
uri: savedUri,
operationMode: fileShare.OperationMode.READ_MODE | fileShare.OperationMode.WRITE_MODE,
};
let policies: Array<fileShare.PolicyInfo> = [policyInfo];
await fileShare.activatePermission(policies)
.then(() => {
console.info('activatePermission success');
})
.catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
console.error(`activatePermission failed: ${err.message}`);
});
}
module.json5 里加上权限声明:
"requestPermissions": [
{
"name": "ohos.permission.FILE_ACCESS_PERSIST"
}
]
几个容易踩的坑:
- 持久化只能对已拿到临时权限的 URI 操作,没经过 Picker 直接拼的 URI 会报 13900001
- 应用卸载后持久化数据会清空,重装需要重新走一遍 Picker + persistPermission
activatePermission要在每次冷启动时调用,不然即使之前 persist 过,这次启动也没权限- 用前可以先
canIUse('SystemCapability.FileManagement.AppFileService.FolderAuthorization')检查设备是否支持
相关文档:授权持久化 | @ohos.fileshare
AI助手这是 HarmonyOS 文件安全模型下的典型问题:应用通过 Picker(如 DocumentViewPicker)选择目录拿到的 URI 只具有临时授权,临时授权在应用退出或设备重启后会被系统清除。因此把 URI 字符串保存下来后,下次启动时该 URI 的授权已经失效,直接读写就会报无权限(典型报错如 13900001 Operation not permitted)。
原因分析
HarmonyOS 对用户文件访问实行"临时授权 + 持久化授权"两级机制:
- 临时授权:Picker 返回的 URI 默认只有临时读写权限,进程退出或设备重启后失效。
- 持久化授权(persistPermission):把临时授权写入系统授权数据库,应用重启、设备重启后仍然保留,相当于"存"。
- 激活授权(activatePermission):把数据库中已持久化的授权加载到当前应用进程的运行时,相当于"取"。应用每次冷启动后,进程内运行时授权是空的,必须重新激活才能读写。
很多开发者只做了 persistPermission(甚至只保存了 URI 字符串),却没有在启动时调用 activatePermission,或者根本没有做持久化授权,就会出现"保存了路径,下次启动提示无权限"的现象。正确的完整方案是三步:申请受限权限 → Picker 选完目录后立即持久化授权并保存 URI → 每次启动时激活已持久化的授权。
实现方案
第一步,在 module.json5 中声明受限权限(该权限需要通过 ACL 方式申请,具体参考官网"申请受限开放权限"文档):
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.FILE_ACCESS_PERSIST",
"reason": "$string:file_access_persist_reason"
}
]
}
}
第二步,Picker 选择目录后进行持久化授权,并将 URI 保存到首选项(示例基于 API 12 及以上版本):
import { picker, fileShare } from '@kit.CoreFileKit';
import { preferences } from '@kit.ArkData';
import { Context } from '@kit.AbilityKit';
// 选择目录并持久化授权
async function selectAndPersistWorkspace(context: Context): Promise<void> {
// 拉起文档选择器,让用户选择工作区目录
const documentPicker = new picker.DocumentViewPicker(context);
const selectOption: picker.DocumentSelectOptions = new picker.DocumentSelectOptions();
selectOption.maxSelectNumber = 1;
// 选择文件夹模式
const uris: Array<string> = await documentPicker.select(selectOption);
if (uris.length === 0) {
return;
}
const workspaceUri: string = uris[0];
// 构造授权策略:对选中目录授予读写权限
const policy: fileShare.PolicyInfo = {
uri: workspaceUri,
grantPermission: {
// 可读可写,按需选择
readonly: false,
// 仅本应用可访问
transfer: false
}
};
// 持久化授权:将临时授权写入系统授权数据库
// 注意:必须在 Picker 返回的临时授权仍有效时调用,且 URI 要原样使用,不要自行解析或拼接
await fileShare.persistPermission([policy]);
// 将 URI 保存到首选项,供下次启动时使用
const pref: preferences.Preferences =
await preferences.getPreferences(context, 'workspace_pref');
await pref.put('workspace_uri', workspaceUri);
await pref.flush();
}
第三步,应用每次冷启动时(推荐放在 EntryAbility 的 onCreate 中)激活已持久化的授权:
import { fileShare } from '@kit.CoreFileKit';
import { preferences } from '@kit.ArkData';
import { Context } from '@kit.AbilityKit';
// 应用启动时激活已持久化的授权
async function activateWorkspaceOnStartup(context: Context): Promise<void> {
const pref: preferences.Preferences =
await preferences.getPreferences(context, 'workspace_pref');
const workspaceUri: string | undefined = pref.getSync('workspace_uri', undefined) as string | undefined;
if (workspaceUri === undefined) {
return;
}
const policy: fileShare.PolicyInfo = {
uri: workspaceUri,
grantPermission: {
readonly: false,
transfer: false
}
};
// 激活授权:把数据库中的持久化授权加载到当前进程运行时
// 持久化是激活的前提,激活后可通过 deactivatePermission 取消激活
await fileShare.activatePermission([policy]);
}
补充说明
- persistPermission 与 activatePermission 的关系可以理解为"存"与"取":persist 只负责把授权写入系统数据库,activate 负责把授权加载到当前进程。每次冷启动后必须对持久化过的 URI 调用一次 activatePermission 才能继续读写,否则即使持久化记录还在,也会报无权限。
- activatePermission 支持传入 PolicyInfo 数组,可一次性批量激活多个目录/文件。
- persistPermission 必须在 Picker 授予的临时授权仍有效时调用;URI 需原样保存使用,不要自行解析或拼接路径。若目录或文件名中包含特殊字符(如 #),需先通过 getUriFromPath 接口处理后再做持久化,否则会报 Invalid path 错误。
- 当用户不再需要该工作区时,可调用 deactivatePermission 取消激活,或调用 revokePermission 撤销持久化授权。
- 如果应用只需要临时访问,也可以在启动时发现授权失效后重新拉起 Picker 让用户再次选择,但持久化授权 + 启动激活的方案体验更好,是文档工具类应用(如编辑器、笔记类)的推荐做法。
相关官方文档可参考开发者官网"选择与保存用户文件-授权持久化"和 @ohos.fileshare(文件分享)API 参考。
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS ArkTS侧获取的文件路径如何传给Native侧读写? (API12+)
HarmonyOS 如何访问非应用文件?比如读写公共目录下的文件等 (API12+)
HarmonyOS 键值型数据库KVStore是否支持多进程读写,是进程并发安全的吗?(API12+)
HarmonyOS 用户获取的这些HarmonyOS版本分别对应的API是哪个版本 (API12+)
设置中定位权限选择始终允许,仍然无法开启定位
如何实现文件和文件夹权限持久化
HarmonyOS 不允许桌面权限后,在系统中打开权限,在桌面路径看不到桌面文件 (API12+)
HarmonyOS 卸载重装应用如何保留权限 (API12+)




































苏公安网备 32011402010933号