1. 先把文件放对位置：小程序的本地文件到底在哪
很多人一上来就写fs.readFileSync('data.txt')，结果报错File not found，一脸懵。我最初做某工具类小程序时也遇到过这种情况，排了半天才明白，小程序里的"本地文件"和你在电脑上理解的"本地文件"不是一回事。
小程序的文件体系分两层：一层是项目目录内的文件，就是你在开发者工具里看到的那堆代码和资源文件，它们会被打包进小程序包；另一层是用户目录下的文件，由小程序运行时通过文件系统接口动态读写，存在用户的设备上。标题里说的"读取本地txt、json"，如果是指随小程序一起发布的静态数据，那你要读的是项目目录内的文件；如果是指用户设备上生成的数据，那是另外一套接口，比如通过wx.chooseMessageFile去选用户手机里的文件，这里我们先聚焦前者，这是最常用、也是坑最多的场景。
项目目录内的文件，读取路径是相对于小程序根目录的。你可以用绝对路径，比如/utils/data.txt，也可以用相对路径../../utils/data.txt，但有个细节容易被坑：在开发者工具里，fs.readFile的相对路径是相对于小程序根目录，而不是相对于当前js文件所在的目录。很多人在某个子页面里写fs.readFileSync('./data.txt')，觉得是读当前页面同级文件，实际跑起来就是文件不存在，这就是路径认知不一致导致的。
还有一个更隐蔽的问题：项目目录内有些文件是不被打包的。比如某些隐藏目录、超过大小限制的文件、或者路径里有特殊字符的文件，真机下载包时会被过滤掉。所以如果你发现编辑器里调试好好的，一上真机就说文件不存在，先查一下这个文件有没有真正随包发布。
要确认文件是否被打包，最直接的方法是查看"上传"时开发者工具提示的包内容，或者用真机调试模式下的"缓存目录"检查实际拉到的文件列表。我碰到过一次很迷的情况：一个配置文件放在了node_modules文件夹里，编辑器能读到，真机永远读不到，后来才意识到小程序的打包规则默认不包含node_modules下的文件，除非显式引用。这类问题排查走弯路特别浪费心情，先把文件放对位置，后面的一切才有意义。
抛开路径不谈，读取方式本身也有讲究。小程序里读本地文件，最常用的是FileSystemManager对象，它提供同步和异步两个版本：readFileSync和readFile。同步版适合页面初始化时直接读取，代码干净；异步版适合读取大文件时避免阻塞页面渲染。不管是哪个版本，你都可以通过指定encoding参数来决定输出的是字符串还是字节流，这个选择直接决定了你会不会遇到乱码，下一节我们展开细说。
2. 读取本地txt文件的标准姿势（附完整代码）
txt文件处理起来最简单，但也最容易踩编码的雷。因为txt本身是纯文本，没有元信息告诉小程序"我是UTF-8还是GBK"，所以读取时你必须自己指定编码。如果指定的编码和文件实际编码不一致，出来的就是一堆�乱码字符。
2.1 实操代码：一次性读出txt内容
假设你有一个数据文件放在项目根目录的/data/notes.txt，内容是UTF-8编码的中文文本。正确写法是这样：
const fs = wx.getFileSystemManager(); // 同步读取，适合文件小、页面初始化时需要立即使用的情况 try { const text = fs.readFileSync('/data/notes.txt', 'utf8'); console.log(text); } catch (e) { console.error('读取失败', e); } // 异步读取，适合大文件或不想阻塞UI的情况 fs.readFile({ filePath: '/data/notes.txt', encoding: 'utf8', success(res) { console.log('异步结果', res.data); }, fail(err) { console.error('读取失败', err); } });这段代码跑通的关键点有两个：一是路径前面必须带斜杠，表示从根目录开始找，/data/notes.txt而不是data/notes.txt；二是必须指定encoding: 'utf8'。如果你不传encoding，返回结果就是一个ArrayBuffer，打印出来是一堆数字，不是人能看懂的文本。
很多初学者会问：既然readFileSync能读，那我是不是应该把文件放到json后缀才能JSON.parse？其实不用，.txt文件只要内容是JSON格式的文本，读取后照样可以JSON.parse。文件后缀只是命名习惯，不决定内容的解析方式。
2.2 为什么乱码：编码不一致是万恶之源
乱码的本质就一句话：写入时用的编码和读取时用的编码对不上。中文字符在UTF-8里占3个字节，在GBK里占2个字节，同样的"你好"两个字，两种编码下的字节序列完全不同。你打开文件看是正常的，是因为编辑器自动帮你猜对了编码；小程序不会猜，你指定什么就是什么。
最常见的乱码场景是：txt文件是在Windows记事本里创建的，记事本默认保存为GBK（也有的系统默认UTF-8），但你在代码里写encoding: 'utf8'，出来的中文就全是�。反过来，文件明明是UTF-8，你指定了GBK，一样乱。
那怎么判断一个txt文件到底是什么编码？给你一个土办法：用开发者工具打开该文件，看右下角或设置里的文件编码，一般会显示当前编码格式。如果显示UTF-8，代码里就用utf8；如果显示GBK，按照我的经验，不建议在小程序里强行处理GBK，因为小程序内置的解码器默认不支持GBK，你需要额外引入第三方库去转码，这在包体积和逻辑复杂度上都不划算。最省事的方案是把源文件转存成UTF-8再放进来，后面第5节我会专门聊这个坑。
2.3 处理读取结果的几种姿势
读出来的字符串，你可以按需处理：直接展示到页面上、拆分每行变成数组、按分隔符解析成对象。比如读一个每一行是一条数据的txt：
const text = fs.readFileSync('/data/list.txt', 'utf8'); const lines = text.split('\n'); // 按换行符拆成数组 const cleanedLines = lines.map(line => line.trim()).filter(line => line.length > 0);注意一个小细节：\n后面的内容可能带着\r，这是Windows换行符残留导致的，行末日习惯用trim()或replace(/\r/g, '')处理一下，否则你匹配内容时会莫名多了不可见字符，排查起来很烦。
还有一个我常用的技巧：如果txt内容是键值对格式，比如name=张三每行一条，可以split之后再来一个map转成对象数组，这样读取流程就变成了一套配置解析器。不过说心里话，如果数据结构比较复杂，txt的解析规则全靠你自己写，不如直接用JSON，后面要讲的方式更省心。
3. 读取本地json数据：require方式和fs.readFile到底怎么选
json文件是移动开发里最标准的配置文件格式，小程序里读取json也有两条路线，很多人不知道它们的区别，选错了方式会踩不同的坑。
3.1 require方式：最直接，但有讲究
如果json文件内容固定、不会在运行时被修改，你可以直接在js里require它，像一个模块那样引入。比如：
const data = require('../../data/config.json'); console.log(data.appName);是不是很简单？但这里有几个隐患你得知道。
第一个是json格式必须极其严格。JSON规范里不允许有注释，不允许有单引号，不允许末尾多逗号。如果你在json文件里写了// 注释，require时直接报错。很多从写JS转过来的同学习惯性在json里加注释，结果编译不过去，还以为是引入方式有问题。
第二个是缓存问题。通过require引入的json数据会被小程序模块系统缓存，如果你在开发过程中改了json文件内容，重新编译后大概率是新的，但如果你在同一个运行周期内想动态改这个对象并恢复原始值，会因为require返回的是同一个对象引用而处处是坑。实测下来，修改require返回对象的属性，会直接改动模块导出的原始对象，下次require还是改动后的值，这是很多做"配置重置"功能时莫名bug的根源。
3.2 fs.readFile方式 + JSON.parse：推荐方案
如果你需要灵活读取，或者json的内容是动态生成的（比如先写入再读取），推荐使用fs.readFile + JSON.parse组合：
const fs = wx.getFileSystemManager(); function loadJson(filePath) { try { const text = fs.readFileSync(filePath, 'utf8'); return JSON.parse(text); } catch (e) { console.error('解析失败', e); return null; } } const config = loadJson('/data/config.json');这里有一个容易翻车的点：JSON.parse要求字符串是合法JSON。如果你在文件保存时，编辑器自动加了一个BOM头（Byte Order Mark），JSON.parse就会报Unexpected token错误。BOM是一个不可见字符，在文件开头有\uFEFF，你在开发者工具里看不见它，但它在。遇到这种情况，parse之前先处理一下：
const text = fs.readFileSync(filePath, 'utf8'); const cleanText = text.replace(/^\uFEFF/, ''); // 去掉BOM头 const data = JSON.parse(cleanText);这个BOM问题我遇到得不算少，尤其当文件从Windows记事本或其他工具编辑过之后，特别容易出现。加上这一行replace，算是一个万无一失的习惯。
3.3 大数据json的加载策略与内存心得
如果你的json文件很大，比如几千条数据、几百KB甚至上MB，两种方式的体验差异就很明显了。require是编译期引入，相当于把整份数据带进了包体且页面加载时就占内存；fs.readFile是运行期读取，理论上你可以在用户操作后按需加载，离开页面时释放引用。
我的经验是：如果json数据超过200KB，尽量避免在多个页面里直接require。因为每个页面都会引到同一份数据对象，小程序运行时对全局对象的内存管理不会主动帮你释放，数据一旦被多处引用，占用的内存就一直在线。改用fs.readFile后，用完把变量置空，配合页面onUnload清理，实际内存占用会好看很多。
对于需要动态加载的场景，还有一种折中方案：把数据按维度拆成多个小json文件，按需加载。比如city.json、region.json、school.json分开，而不是一个大而全的all.json。这既解决了首次加载时间，也让单个文件的维护变得轻松，后续更新数据时也不用整包替换。
3.4 JSON.parse失败的常见场景速查
实践中JSON.parse报错几乎都是以下几类，我整理一张表方便你对照：
| 报错特征 | 大概率原因 | 解决办法 |
|---|---|---|
Unexpected token / | json里有注释//或/* */ | 删除注释，用其他方式描述说明 |
Unexpected token '（单引号） | json里用了单引号 | 全部改成双引号 |
Unexpected token } | 末尾多了一个逗号 | 检查每一项之间的分隔符 |
Unexpected token \uFEFF | 文件带BOM头 | 用replace(/^\uFEFF/, '')清洗 |
Unexpected end of JSON input | 文件内容被截断或为空 | 确认文件完整写入后再读取 |
凡是报错，第一步永远是console.log(text)把原始字符串打印出来看。不要猜，直接看真实内容，90%的问题一眼就能定位。
4. 彻底解决乱码：从编码原理到落地方案
如果说读取文件是"手里有粮"，那处理乱码就是"做饭不糊"。乱码问题看起来千奇百怪，但你把它拆成三种情况，逐个击破就完了。
4.1 情况一：UTF-8文件、强制按utf8读但还乱码
如果你确认文件是UTF-8，代码里也传了utf8，读出来还是乱码，那多半不是编码不对，而是文件内容本身损坏或被二次编码过。比如你在某个在线工具里把内容复制粘贴，工具自动做了一次Unicode转义，存到文件里变成了\u4f60\u597d而不是"你好"，页面显示的时候没做反转义，自然是一堆转义符号。
解决办法是把读取结果先打印出来看，如果内容是\u开头的转义序列，用JSON.parse转一下：
const text = fs.readFileSync(filePath, 'utf8'); const decoded = JSON.parse(JSON.stringify(text)); // 注意这不保险其实更稳定的做法：如果源文件本身就是JSON格式，直接读取后JSON.parse就会自动还原转义字符。不需要额外处理。如果是txt且只有部分转义字符，建议在保存文件时就确保内容是真正的中文，而不是转义序列。这种源数据问题，治源头最省事。
4.2 情况二：文件是GBK编码，小程序怎么读
这是最让人头大的情况。小程序核心库内置的解码器只支持UTF-8，直接指定gbk会报编码不支持。网上常见的方案是引入iconv-lite这类转码库，在小程序里运行时把ArrayBuffer转成GBK解码后的字符串。
我的实测结论是：这条路理论可行，但非常不推荐。原因有三：第一，iconv-lite是Node环境下的库，直接在小程序里用需要适配，你得把它的核心解码逻辑拆出来或找适配好的包，搞下来的代码量和踩坑量都很大；第二，转码库会导致包体积增加，对注重体积的小程序不友好；第三，GBK转码过程中遇到生僻字、特殊符号，库里处理不好的情况很常见，转出来依然有零星乱码。
如果你必须读取一份GBK编码的txt（比如第三方提供的固定数据文件），我的建议是：先用一个本地脚本一次性把文件转成UTF-8，再放进小程序目录。转码脚本可以这样写，比如用Node的iconv-lite库，在电脑上批量处理：
const fs = require('fs'); const iconv = require('iconv-lite'); const buf = fs.readFileSync('legacy.txt'); // 原文件是GBK const text = iconv.decode(buf, 'gbk'); fs.writeFileSync('new-utf8.txt', text, 'utf8');这样处理一次，小程序里永远只读UTF-8，后面不管谁接手维护，都不需要再和编码较劲。你可能会觉得这不是"根治"，但在工程里，让数据源侧统一编码，比在运行时做各种容错要可靠得多。
4.3 情况三：读取ArrayBuffer后如何转字符串
有时候你没传encoding，readFileSync返回的是ArrayBuffer，这时候怎么变成字符串？
const buffer = fs.readFileSync('/data/notes.txt'); // 不传encoding，拿到ArrayBuffer const text = new TextDecoder('utf-8').decode(buffer); console.log(text);TextDecoder是标准的Web API，在小程序的基础库版本较新时可以使用。如果你的基础库版本比较老，或者担心兼容性，可以退一步用String.fromCharCode配合Unicode解码：
const bytes = new Uint8Array(buffer); let text = ''; for (let i = 0; i < bytes.length; i++) { text += String.fromCharCode(bytes[i]); }但注意，String.fromCharCode这种逐字节拼接的方式，只适合纯ASCII文本，遇到中文会乱。所以要想处理UTF-8变长字符，本质上还是要靠TextDecoder或类似解器来处理。所以我的经验是：宁可一开始就用encoding参数读出字符串，也别绕这一圈。ArrayBuffer转字符串的路看起来很"底层"，实际在小程序环境里坑更多。
4.4 乱码问题自查清单
我这里给你一份可以直接用的检查顺序，按顺序查完，乱码问题基本能定位：
- 文件实际编码是什么？（用编辑器或命令行
file命令确认） - 读取时指定encoding是否正确？
- 文件是否有BOM头？（JSON.parse报Unexpected token时尤其注意）
- 文件内容是否被转义序列污染？（打印内容看是不是
\uXXXX） - 是否经过第三方工具二次编码？（复制粘贴最容易出这种事）
- 真机和编辑器行为是否一致？（有时候编辑器替你做了容错，真机不会）
5. 常见问题排查与避坑记录
这部分是我实际踩坑的记录，每个问题背后都是一段熬夜经历，希望你能避开。
5.1 路径写错导致的"文件不存在"
readFileSync报错File not found的排查顺序：
- 检查路径开头的斜杠。
/data/a.json和data/a.json在小程序里含义不同，前者从根目录找，后者可能从当前代码目录找，容易出错。 - 检查文件名大小写。小程序真机环境对大小写敏感，特别是iOS端，
Config.json和config.json是两个文件。开发工具里偶尔不敏感，一到真机就现原形。 - 检查是否是分包路径。如果文件在分包目录里，主包去读取分包路径的文件会失败。这种情况要调整目录规划。
5.2 真机和编辑器行为不一致的典型场景
编辑器里一切正常，真机调试就报错，这类问题最气人。我总结过三个高频差异点：
第一，相对路径解析差异。在开发者工具中，fs.readFileSync的路径解析相对宽松，你写data/config.json它也能找到。但真机上严格按规则来，data/config.json会被解析成"当前代码目录下的data目录"，如果你的页面在子目录，就会找不到。解决方案是统一用/开头的根目录路径。
第二，异步回调时序。真机上异步读取的success回调时机可能比编辑器晚，如果你在回调里依赖了未初始化页面数据，表现会不一致。建议大文件读取时用 async/await 或把整个流程包裹在Promise里，不要在回调里直接操作页面数据。
第三，基础库版本差异。某些编码处理和API参数在低版本基础库上兼容性差。真机上用的基础库版本可能和编辑器里的默认版本不同，必要时去详情面板设置里调整。
5.3 内容更新了但小程序里没变化
这是一个很容易被误解的点。你改了json文件内容，重新编译小程序，页面里加载的还是旧数据。原因通常不是读取逻辑有问题，而是cdn或本地缓存没刷新。
如果你通过require引入json，开发模式下编辑器的编译缓存可能没有检测到纯数据文件的变化。处理方法是：在开发者工具菜单里执行"清缓存并重新编译"，或者直接改一下js文件的任意代码触发重新编译。如果是真机上运行的预览版，需要重新上传代码再预览，预览版的缓存策略有时很顽固。
更彻底的做法是把数据版本号写进json文件里，读取成功后校验版本号，发现不一致就提示用户下拉刷新或重新加载。这招对于经常迭代数据内容的应用特别管用。
5.4 文件体积与包体积的权衡
小程序主包有大小限制（2MB上限），如果你把大量json放进主包，很容易触及红线。我通常这样规划：
- 主包只放必需的配置项，尽量精简，例如应用标题、主题配置等小体积数据。
- 大体积数据文件放到分包目录，按业务模块拆分使用。
- 如果数据量特别大且需要频繁更新，考虑从后端接口动态获取，而不是打进包里。
你可能觉得这和第2节讲的"读取本地文件"冲突了，其实不冲突。本地静态读取适合数据固定、离线可用、无需实时更新的场景；接口动态获取适合频繁变化的数据。两个方案按需选，别在一个方案上死磕。
5.5 一个独家调试技巧：快速定位读取状态
每次写文件读取代码，我都会在开发阶段加一段诊断日志，把每个关键节点的结果都打出来：
const text = fs.readFileSync(filePath, 'utf8'); console.log('raw text length:', text.length); // 确认非空 console.log('first 50 chars:', text.substring(0, 50)); // 快速确认编码是否正确如果你想更省事，可以在app.js的onLaunch里做一个全局文件读取自检函数，调用时传入路径列表，自动把每个文件的长度和首字符片段打出来。上线前删除这些调试代码即可，但如果只是console.log保留在代码里，在正式环境也基本不会影响性能，只是日志看着乱。
5.6 最后一个重要提醒：直接require json时不要改它
我在第3节提过require返回的是同一个对象引用，这里再举一个具体例子。你写：
const config = require('../../data/config.json'); config.appName = '新名字';这会直接修改模块导出对象，下次任何页面require这个json，拿到的都是改过的数据。如果你的业务里存在"临时修改配置再恢复原样"的需求，不要改require拿到的对象。用JSON.parse(JSON.stringify(config))拷贝一份再改，就不会污染数据源。
6. 踩过几次坑以后，我的个人选择
写了这么多，最后说点实在的。我现在处理小程序本地数据的方案基本固定了：能转成UTF-8的，在源头统一转好；能拆成小文件的，不分装进同一个大包；能按需读取的，绝不用require把数据全量塞进内存。
有一次做某数据展示类小程序，甲方给了一个2MB的GBK编码txt数据文件，说必须原样解析展示。我研究了一整天转码方案，最后决定写个本地脚本把GBK转UTF-8，再按城市维度拆成7个小json文件，按用户选择动态加载。最后实现的效果是：包体积降下来了，页面首屏速度更快，乱码问题完全消失，甲方反馈"你们这个解码做得好，一点乱码没有"——其实真正的关键在于没有在运行时解码，而是提前把编码问题在数据侧解决掉了。
这种思路放到你自己遇到的项目里也适用：文件读取的坑，大多数不是因为小程序难用，而是数据源头没有规范化。路径统一用绝对路径、编码统一用UTF-8、数据格式统一用合法JSON，按这三个"统一"去做，90%的问题都能在开发阶段避免。剩下那10%，无非是缓存和真机差异，有一份清晰的排查清单对照，也能很快定位。希望你少走点弯路。
