摘要
在鸿蒙 HarmonyOS 应用开发中，很多开发者在尝试读写文件时都会遇到“无法访问文件”“写入失败”或“路径无效”等问题。特别是新接触 ArkTS 或 JS 接口的同学，常常会被权限配置、沙箱机制和 API 使用搞得晕头转向。这篇文章就从权限配置、路径选择、API 使用等角度入手，带你逐步解决鸿蒙中文件访问失败的问题，并提供完整的代码 Demo 和应用场景实践。
引言
在移动应用开发中，文件系统的访问是最基础也是最常用的功能之一，比如缓存用户数据、保存图片、读取配置文件等等。而鸿蒙系统由于其独立架构和沙箱机制，相比传统 Android 文件访问方式有一些区别。如果不遵循规范和权限配置，就可能导致你读写文件完全无效。
文件系统访问失败的原因分析与解决方案
权限声明必须写对
首先在 module.json5 中声明文件读写权限：
"requestPermissions": [
{
"name": "ohos.permission.READ_MEDIA"
},
{
"name": "ohos.permission.WRITE_MEDIA"
}
]
不声明，系统直接拦截，写再多代码都没用。
路径写错？换成标准沙箱路径！
鸿蒙应用有严格的沙箱限制，文件只能写入你自己的应用目录。路径一般是这样：
internal://app/表示应用私有目录，推荐用于读写私有数据。
路径拼错、目录权限不够都会导致访问失败。
API 使用方式标准示例
示例代码：读写文件
const file = require('@system.file');
// 写入文件
file.writeText({
uri: 'internal://app/test.txt',
text: 'Hello, HarmonyOS!',
success: function () {
console.log('写文件成功');
},
fail: function (data, code) {
console.error('写文件失败，错误码：' + code);
}
});
// 读取文件
file.readText({
uri: 'internal://app/test.txt',
success: function (data) {
console.log('读文件成功，内容：' + data.text);
},
fail: function (data, code) {
console.error('读文件失败，错误码：' + code);
}
});
应用场景示例
场景一：保存用户的设置项到本地文件
用户选择了某个偏好设置，比如夜间模式，我们希望下次启动自动加载。
file.writeText({
uri: 'internal://app/user-preference.txt',
text: JSON.stringify({ theme: 'dark' })
});
场景二：记录操作日志供开发者查看
let log = `[${new Date().toISOString()}] 用户点击了按钮`;
file.appendText({
uri: 'internal://app/app.log',
text: log + '\n'
});
场景三：读取配置模板并初始化界面
file.readText({
uri: 'internal://app/config.json',
success: (res) => {
let config = JSON.parse(res.text);
console.log('加载配置成功：', config);
}
});
QA 问答环节
Q1：模拟器里测试为什么失败？
模拟器部分版本可能不支持写文件或沙箱路径写保护，建议真机调试。
Q2：文件路径一定要写 internal:// 开头吗？
是的。HarmonyOS 文件路径不能随便写，要符合系统沙箱路径规范。
Q3：能不能跨应用访问文件？
不行，除非是公共媒体库（如图片/视频），否则沙箱机制禁止访问其他应用目录。
总结
鸿蒙系统中访问文件看似简单，实际要踩的坑还不少。从权限到路径，从 API 到沙箱机制，每个环节都不能出错。总结一下：
- 权限必须声明，别漏掉
WRITE_MEDIA - 路径写对，
internal://app/是你最佳的私有空间 - 用官方提供的 API，不要写原生 Node 的 fs 模块
掌握了这些套路，你的文件访问就稳了。
如果你还想要一个 FileHelper 工具类，统一封装读写逻辑、异常处理、缓存路径，我可以直接给你写一个 ArkTS 模块。需要的话直接留言，我马上安排！
