STM32嵌入式C++14实战：轻量级特性解决中大型项目结构性瓶颈
2026/9/15 21:25:21
我在数据处理的圈子里混得久了，越来越觉得Matlab的fprintf是个被严重低估的基础功能。不少人处理计算结果时，第一反应是save成.mat，或者直接点工作区右键导出Excel，可一旦要对接到自研工具、第三方程序或者纯文本日志系统，txt才是最通用的中间格式。fprintf就是那个能把内存里的数字、字符串，按照你指定的格式一字不差写进文本文件的函数。这篇教程不绕弯子，直接从最底层的格式控制逻辑讲起，带你一步步把计算结果用fprintf写入txt，覆盖格式化输出、数据对齐、日志记录、大数据量性能优化这些高频场景。
这套东西适合谁？刚接触Matlab、还在用disp和手动复制粘贴的人；写科学计算脚本、经常要批量导出数据给后续程序用的研究者；以及所有被“小数位数不对”“文件里乱码”“数据没换行”折磨过的朋友。只要跟着实操走一遍，你会发现格式化写入本质上就是“填空”，没有那么玄乎。
1. fprintf是什么——格式符和转义符的底层逻辑
1.1 一次fprintf调用的完整心智模型
很多初学者第一次看到fprintf的语法会觉得吓人，其实它拆开看就三部分：往哪写、按什么格式写、写什么数据。在C语言里fprintf是标准库函数，Matlab把这个思想完整搬了过来，只是句法更贴近矩阵风格。
fprintf(fid, formatSpec, A1, A2, ...)fid是文件标识符，由fopen返回；formatSpec是格式模板；A1, A2是需要写进文件的数据。你可以把formatSpec想象成一张空白的填空表，里面写满了%d、%f、%s这些占位符，而A1, A2就是按顺序填进去的内容。比如：
fprintf('%d 的平方是 %d\n', 3, 9);这句的意思是：把第一个参数3填入第一个%d位置，把第二个参数9填入第二个%d位置，\n表示换行。输出结果是：
3 的平方是 9你可能会问：这和直接用disp(['3的平方是', num2str(9)])有什么区别？区别就藏在“格式化”三个字里。fprintf可以让你控制整数占几位、小数保留几位、左对齐还是右对齐、科学计数法用几位有效数字，这些精确控制最终会直接影响txt文件的可读性和下游程序的解析难度。而且fprintf写入文件的速度远快于频繁调用num2str拼接字符串。
1.2 常用格式符与转义符速查表
格式符是fprintf的核心，一个%加一个字母就定义了一种数据类型。我用下来最常用的就下面这几个，建议先把它们记牢：
| 格式符 | 含义 | 输出示例 |
|---|---|---|
%d | 整数（十进制） | 42 |
%f | 浮点数（小数点式） | 3.141593 |
%e | 科学计数法（小写e） | 3.141593e+00 |
%E | 科学计数法（大写E） | 3.141593E+00 |
%g | 根据数值大小自动选%f或%e | 3.14159 |
%s | 字符串 | hello |
%c | 单个字符 | A |
%% | 输出一个百分号 | % |
光有格式符还不够，实际写文件时“宽度”和“精度”同样重要。写法是%宽度.精度格式符，比如：
| 写法 | 效果 | 示例 |
|---|---|---|
%6.2f | 总宽度6位，小数保留2位，右对齐 | 3.14 |
%-10s | 左对齐，占10位 | hello |
%08.3f | 总宽度8位，小数3位，空白用0填充 | 003.142 |
%.8e | 科学计数法，小数部分保留8位 | 3.14159265e+00 |
转义符则是用来处理换行、制表符这类不可见字符的。Matlab里的常用转义符如下：
\n：换行\t：制表符（Tab）\r：回车\\：输出一个反斜杠\'：输出单引号\b：退格
一个非常容易踩的坑是：在Windows下用记事本打开txt文件时，如果每行结尾只有一个\n，文件可能不会正常换行，而是显示成一行黑块或者全部挤在一起。这是因为Windows传统文本文件要求\r\n作为换行序列。后面第2节会讲用'wt'模式自动处理，这里先留个印象。
2. 从零开始：第1个fprintf写txt的完整流程
2.1 最简可运行例子：把正弦采样结果写入txt
我不太喜欢只讲理论，直接上一个能跑的完整例子。假设你要生成一组正弦波采样数据，横坐标是时间，纵坐标是采样值，想把这两列数据存成一个带列头、带对齐格式的txt文件。完整代码如下：
% 生成数据 t = 0:0.01:1; % 0到1秒，步长0.01 y = sin(2*pi*5*t); % 5Hz正弦波 % 打开文件，'wt'表示写入文本模式 [fid, msg] = fopen('sine_data.txt', 'wt'); if fid < 0 error('无法打开文件: %s', msg); end % 写表头 fprintf(fid, '%s\t%s\n', 'time(s)', 'amp'); % 写入数据，每行两列，各保留6位小数 for i = 1:length(t) fprintf(fid, '%.6f\t%.6f\n', t(i), y(i)); end % 关闭文件，确保数据落盘 fclose(fid); disp('数据已保存到 sine_data.txt');运行完，打开sine_data.txt，你应该看到类似这样的内容：
time(s) amp 0.000000 0.000000 0.010000 0.314159 0.020000 0.618034 ...这里有几个关键点需要拆开讲。第一，fopen返回的fid如果是一个负值，说明打开失败，第二个返回值msg会告诉我们失败原因，通常是因为路径不存在、没有写入权限，或者文件名包含了非法字符。第二，fclose(fid)绝不能省，它负责把缓冲区的数据真正写到磁盘，不关文件就退出，最后部分数据可能丢失。
2.2 文件打开模式怎么选：w、wt与a的差别
fopen的第二个参数看起来只是个短字符串，实际上它决定了文件以何种方式打开，直接影响文件内容是否会覆盖、是否自动换行转换。我把常用模式整理成了下表：
| 模式 | 行为 | 典型场景 |
|---|---|---|
'w' | 覆盖写入，文件不存在则创建 | 每次运行都生成全新数据文件 |
'wt' | 覆盖写入，以文本模式打开 | Windows下写txt推荐 |
'a' | 追加写入，文件不存在则创建 | 日志累积，不覆盖旧记录 |
'at' | 追加写入，文本模式 | Windows下做日志 |
'r' | 只读 | 需要读取已有txt |
'r+' | 读写，不截断 | 边读边改 |
'w+' | 读写，覆盖 | 少见，需要同时读新文件时 |
我个人的习惯是：只要明确要写txt，一律用'wt'。原因很简单，Windows系统默认换行符是\r\n，如果你用'w'写文件，\n不会自动转换成\r\n，最终生成的txt拿到记事本里就乱作一团。'wt'模式会在你写入\n时自动替换成当前的平台换行序列，既保证Matlab内部逻辑不变，又保证外部编辑器打开时视觉正常。
追加模式'a'则适合做运行日志。比如一个训练脚本要跑很多轮，每轮都想把损失值追加到同一个文件末尾，用'at'就不怕覆盖前一次的结果，也不需要手动读旧文件再拼接。
3. 保存计算结果的几种典型写法
3.1 二维数据循环写入：最常用的数据导出套路
处理仿真结果时，最典型的场景是把矩阵数据逐行写入txt，每一行代表一个样本或一个时间步，每一列代表一个变量。假设你有一个data矩阵，行为时间步，列为通道数：
data = randn(10, 4); % 10行4列的随机数据模拟计算结果 [fid, msg] = fopen('matrix_result.txt', 'wt'); if fid < 0 error('无法打开文件: %s', msg); end % 先写列标签 fprintf(fid, 'ch1\tch2\tch3\tch4\n'); % 三重循环：遍历每一行，每一行内拼接四个字段 for i = 1:size(data, 1) for j = 1:size(data, 2) if j < size(data, 2) fprintf(fid, '%.6f\t', data(i, j)); else fprintf(fid, '%.6f\n', data(i, j)); end end end fclose(fid);内层循环的判断是为了在行尾输出换行符。这里的写法完全可控，任何时候想往某一行中间插入一个特殊标识都很方便。如果你的数据规模不大，直接这么写完全没问题；但数据到几十万行时，这种双重循环会明显变慢，第4节会讲优化办法。
注意：写入时
%.6f意味着变量按浮点数输出，但data矩阵里如果恰好有整数或复数类型，fprintf会按照实部虚部规则处理，复数的虚部默认不会单独输出，需要手动拆real和imag。
3.2 表头、说明与对齐排版的实现
txt文件不是只能塞数字，很多场景需要带标题、带说明、带单位。用fprintf写表头非常自然，因为%s就能把字符串内容填进去。比如我想生成一份带注释的数据文件：
[fid, msg] = fopen('report.txt', 'wt'); if fid < 0 error('无法打开文件: %s', msg); end fprintf(fid, '%s\n', '===================================='); fprintf(fid, '%s\n', 'Experiment Report'); fprintf(fid, 'Date: %s\n', datestr(now, 'yyyy-mm-dd HH:MM:SS')); fprintf(fid, '%s\n', '===================================='); fprintf(fid, '%-12s %12s %12s\n', 'Index', 'Voltage(V)', 'Current(A)'); fprintf(fid, '%s\n', '------------------------------------'); for i = 1:5 V = 12.5 + 0.1*i; I = 0.5 - 0.02*i; fprintf(fid, '%-12d %12.3f %12.3f\n', i, V, I); end fclose(fid);%-12s表示左对齐占12位，%12.3f表示右对齐占12位、小数3位。这种定宽对齐在生成报告类txt时非常有用，列与列不会挤在一起，用任何文本编辑器打开都像表格一样整齐。用datestr(now, 'yyyy-mm-dd HH:MM:SS')动态写入生成时间，会让数据文件自带宽信息，这在长时间仿真中尤其重要。
很多新手写表头时会习惯性地用disp然后复制粘贴，一遇到几百个文件的批量处理就彻底崩溃。fprintf一笔流水线操作，一个循环下来所有文件都带同样格式的表头。
3.3 fprintf vs dlmwrite vs writematrix，到底该用谁
Matlab里能写文本文件的远不止fprintf，像dlmwrite、writematrix、csvwrite都是可选方案。但它们各自的定位完全不同，用错地方就会绕远路。
| 函数 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
fprintf | 格式完全可控，能自由编排文本与数字 | 代码量较大 | 需要复杂格式、表头、对齐、混合文本 |
dlmwrite | 一行代码写矩阵，支持分隔符 | 格式控制弱，表头麻烦 | 快速导出纯数值矩阵 |
writematrix | 支持表格、矩阵，性能好 | 列头需要额外处理 | 与table配合导出 |
csvwrite | 写CSV逗号分隔 | 已被writematrix取代，格式限制多 | 老项目中还能见到 |
举个实际例子：如果你只需要把1000行3列的数值矩阵导出成tab分隔的文件，dlmwrite的一行代码显然更香：
dlmwrite('quick.txt', data, 'delimiter', '\t', 'precision', 6);但同时你有“带表头、时间戳、行注释”这类需求时，dlmwrite就会很别扭，你得先拼接表头为另一段字符串，还得处理追加模式。而fprintf就像一个随时可以暂停的打印机，想在那一段插入什么内容都行。
我的建议是：工程脚本里，如果只是临时看数据，用dlmwrite或writematrix；如果是正式的离线数据文件、给第三方系统解析的数据文件、需要长期存档的计算结果，一律用fprintf，格式规范可控，后期好维护。
4. 进阶实战：日志文件、高精度与大数据的写入优化
4.1 用fprintf记录程序运行日志
写长时间运行的脚本或算法时，你肯定不想每步都disp一下，那样既刷屏又无法复盘。更好的做法是边运行边把进度写入日志txt，既不影响命令行交互，又能保留完整记录。
下面是一个模拟训练过程的日志示例：
logFile = 'train_log.txt'; [fid, msg] = fopen(logFile, 'at'); if fid < 0 error('无法打开文件: %s', msg); end % 记录脚本起点 fprintf(fid, '[%s] === Training Start ===\n', datestr(now, 'HH:MM:SS')); for epoch = 1:10 loss = exp(-epoch/3) + 0.01*randn(); acc = 1 - exp(-epoch/4) + 0.005*randn(); fprintf(fid, '[%s] Epoch %02d | Loss: %.6f | Acc: %.4f\n', ... datestr(now, 'HH:MM:SS'), epoch, loss, acc); pause(0.5); % 模拟计算耗时 end fprintf(fid, '[%s] === Training Done ===\n', datestr(now, 'HH:MM:SS')); fclose(fid);这个写法有几个细节值得借鉴。追加模式'at'保证每次运行脚本都不会覆盖上一次的日志；时间戳随行记录，方便定位某个时刻的状态；Epoch %02d里的02表示整数部分占两位，不足补零，这样日志里的编号对齐更好看。
与disp相比，日志文件的价值在于“事后可查”。跑几十个小时的实验，突然在某个时间点崩了，回看日志就能知道最后一步做了什么，这个能力在disp刷屏模式下是没有的。如果你还想同时输出到命令行，可以用fprintf('%s', ...)再打一遍，反正格式模板是同一个。
4.2 科学计数法位数与有效数字控制
科学计算里经常遇到极大或极小的数值，比如1e-15、3.5e10，这种数用%f打印会变成一长串0，既占空间又难读。%e和%g是专门处理这种场景的方案。
fprintf(fid, '%.4e\n', 1.23456789e-15); fprintf(fid, '%.4g\n', 1.23456789e-15); fprintf(fid, '%.4f\n', 1.23456789e-15);输出分别是：
1.2346e-15 1.235e-15 0.0000%.4e会固定输出科学计数法并保留4位小数，%.4g则会根据数值范围自动决定用小数还是科学计数法。很多科学家做数据存档时喜欢用%.10e或%.15e，这样能保留双精度浮点的绝大部分有效数字，回读时不会因为四舍五入损失精度。
这里有个容易犯的错：如果你用%f打印1e20，会输出一个21位的大数字，再转回数值时，精确到小数点后第几位已经毫无意义，因为浮点数本身的精度极限就在那里。所以当你要保存“计算结果”给后续程序做精密计算时，建议保留足够位数的有效数字，比如：
fprintf(fid, '%.15e %.15e\n', x, y);这样txt文件里的每个数字都能完整还原double的精度，缺点是文件体积变大。精度和体积之间怎么取舍，取决于下游程序对精度的需求，没有绝对标准。
4.3 大数据量写入慢？这样改写性能翻倍
用for循环逐行fprintf，遇到几十万行数据时，确实会有卡顿。我早期自己写数据导出脚本时就踩过这个坑，一个50万行的矩阵，循环写法跑了快一分钟，后来改成向量化写法，两三秒就完事。核心思路是：让fprintf一次性接收整个向量或矩阵，而不是一行一行喂给格式串。
% 慢速写法：for循环逐行写 for i = 1:N fprintf(fid, '%.6f %.6f\n', x(i), y(i)); end % 快速写法：格式串复用 + 向量参数 fprintf(fid, '%.6f %.6f\n', [x; y]);第二种写法的关键在于：当formatSpec被应用到多个数据元素时，Matlab会循环使用格式串，直到参数耗尽。[x; y]把两个行向量拼成2行N列的矩阵，fprintf会逐列读取，每一列填入%.6f %.6f\n，效果就等于一个循环，但运行速度要快得多。
如果你的数据是矩阵data，希望每行保存为一个样本，可以把矩阵转置：
fprintf(fid, '%.6f\t%.6f\t%.6f\n', data');这里data'把每一列变成fprintf的一次填充，假设data是3列，那么每条格式串消耗3个值。这个技巧要小心：fprintf是列优先填充的，也就是说它会按矩阵的列顺序一个一个取数，所以矩阵形状必须和格式串的设计严格对应。
提示：当矩阵维度很大、格式串很复杂时，一次性传入大量数据会占用较多内存。如果运行环境内存紧张，可以分块写，例如每5000行写一次，既保速度又不爆内存。
5. 常见问题排查与经验速查
5.1 从“乱码”到“格式乱掉”的典型故障表
我根据自己平时的使用经验和与同行交流的情况，把fprintf写txt最常碰到的几类问题汇总成了一张表：
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
文件里出现%d、%f等原样文本 | 格式串写错，或忘写参数列表 | 检查formatSpec是否有%符号，确保参数数量匹配 |
| 中文字段保存后乱码 | Matlab默认编码与目标编辑器编码不一致 | 统一使用UTF-8编码，或用英文字段 |
| 每行没有换行，全挤在一起 | 没写\n，或Windows下忘了用'wt'模式 | 在文本模式打开文件，或在格式串中显式写\n |
| 小数位数不对，四舍五入误差 | %f默认保留6位，或格式串精度写错 | 用%.10f等方式显式指定精度 |
| 报错“未定义与 'cell' 类型的输入参数相对应的函数 'fprintf'” | 传入的数据是元胞数组而非数值或字符数组 | 先cell2mat或循环处理每个元胞 |
| 输出到命令行而不是文件 | fprintf第一个参数没传fid | 写文件时必须确保第一个参数是fopen返回的标识符 |
| 文件写了一半程序崩溃，旧数据丢失 | fprintf的缓冲机制，未调用fclose | 用try-catch-finally确保关闭文件，或用onCleanup |
fprintf向命令行输出和向文件输出在语法上只差一个fid参数，但这一个参数的区别经常让新手抓狂。我见过不少人在函数里调试时一切正常，一改成写文件就报“输出不是整数”之类的错误，最后发现是fid传成了1——fid=1恰好在Matlab里被默认当作标准输出，所以又打到命令行去了。
5.2 忘写fclose的坑与文件句柄规范
在Windows下打开一个txt后不关闭，再尝试用其他程序打开或删除它，往往会提示“文件被占用”。即使是在Matlab内部，忘记关闭的文件句柄也会持续占用资源，处理成百上千个文件时，最终可能导致“打开文件过多”之类的运行错误。
更隐蔽的问题在于数据完整性。fprintf写入文件时通常有缓冲机制，也就是说你的数据先进入内存缓冲区，再异步刷到磁盘。只有调用fclose或fflush(fid)，缓冲区里的剩余数据才会被真正落盘。如果脚本在写了一半时崩溃，日志文件末尾很可能是缺数据的。
一个稳妥的写法是用try-catch-finally：
fid = fopen('important.txt', 'wt'); if fid < 0 error('无法打开文件'); end try fprintf(fid, '%s\n', 'begin'); % 你的业务逻辑... fprintf(fid, '%s\n', 'end'); catch ME disp(['出错: ', ME.message]); finally fclose(fid); endfinally保证无论代码执行成功还是抛出异常，最终都会执行fclose。如果你懒得更复杂的结构，至少也要在脚本最后显式fclose，并且养成习惯：每次fopen都要在心里问一句“这个文件我哪里关闭”。这个基本素养，很多老手都未必做得好。
5.3 跨平台换行和编码问题的成熟解法
Linux和Windows的换行符不同，这可能是跨平台数据交换时最多见的坑。Linux通常只有\n，Windows传统上要求\r\n。如果你在Windows下用'w'模式写了一个只有\n的文件，拿到Linux下用Vim打开，会看到每行末尾多出一个^M；反过来，在Linux下生成的\n文件拿到Windows记事本打开，换行失效，整个文件变成一行。
成熟的做法分两层：第一层是在Matlab中统一用'wt'或'at'模式打开文件，让Matlab自动处理当前平台的换行转换；第二层是如果这个txt文件将来一定要跨平台传递，而且你无法控制接收方环境，最好在生成时就固定使用\r\n，或者生成后统一转换。
编码问题同样值得关注。Matlab老版本默认使用系统本地编码（Windows下可能是GBK），如果你在文件里写了中文字段，再拿到UTF-8环境下打开就会乱码。我的习惯是：写txt时尽量只用ASCII字符，也就是纯英文、数字和符号；如果必须包含中文，就显式要求Matlab使用UTF-8编码写入。
比较省事的方案是用fopen(..., 'wt', 'n', 'UTF-8')这种写法来指定编码，不同环境下的支持程度略有差异，但用这个方法基本能满足大部分场景。做数据交换和存档时，纯ASCII配合UTF-8是兼容性最保险的组合。
6. 最后分享一条关于格式化写入的长期经验
fprintf这个函数看似基础，但它在我多年的数据工作里几乎每天都在用。相比各种“一键导出”的高级函数，fprintf的优势不在于快，而在于可预期——写出来的文件每一行、每一列长什么样，我心里清清楚楚；下游程序解析时不需要做各种“宽容处理”，格式约定好就不会变。
如果你今天只记住一件事，那请记住：所有需要长期保存、需要被其他程序重复读取的文本数据，都应该用fprintf显式控制格式，而不是把格式交给系统默认。日子久了你就知道，一个字段宽度固定的txt文件，能让后续无数个对接环节省下大量沟通和修改成本。遇到格式对不齐、乱码、精度丢失的问题，再回头看看这篇教程里的排查表，多数情况几分钟就能解决。