matlab-import-export-data

MATLAB 数据导入/导出

MATLAB 数据 I/O 指南——正确处理分隔符、区域设置、特定格式的注意事项和常见错误消息。

适用场景

• 在 MATLAB 中使用 readtable/writetable/detectImportOptions 读取或写入 CSV、Excel、Parquet 或 JSON 文件
• 排查数据 I/O 错误（容易误导的消息、“找不到文件”的各种情况）
• 从 URL 或需要身份验证的 REST API 端点读取数据
• 导入非英语区域设置的数据（欧洲小数格式、分号）
• 验证导入的数据，避免静默损坏（NaN、65535、类型扩展）
• 读取压缩文件或包含非标识符键的 JSON
• 读取或写入文本文件（使用 readlines/writelines，而非 fopen/fgetl/fprintf）
• 读取或写入 XML 文件（使用 MAXP 提供程序，而非旧版 JAXP）

不适用场景

• 可能无法装入内存的大型文件，或需要在 tall 数组、datastore 和并行工作流之间进行选择（使用 matlab-choose-big-data-solution 技能）
• 通过 ODBC/JDBC 访问数据库——读取、写入或查询关系数据库（使用 matlab-use-database 技能）
• 对大型 CSV/Parquet/JSON 文件执行基于 SQL 的查询，以便在分析前缩减数据（使用 matlab-use-duckdb 技能）
• 从 MDF/MF4/BLF/ASC 日志文件导入车辆数据，或解码 CAN/LIN 总线（使用 matlab-import-export-vehicle-data 技能）
• 使用 CAN/CAN FD/J1939 配置车辆网络通信（使用 matlab-use-vehicle-network 技能）
• 为传感器融合工作流导入跟踪数据（使用 matlab-import-tracking-data 技能）
• 医学图像数据——DICOM、NIfTI 或 Analyze 格式（使用 matlab-process-images 技能）
• 市场或金融数据流（使用 matlab-access-datafeed 技能）
• Simulink 数据记录或信号 I/O（使用 Simulink 专用工作流）
• 图像或音频文件 I/O（imread、audioread——属于不同领域）
• 流式或实时数据采集（使用 Data Acquisition Toolbox）
• 文件系统操作、路径处理或文件夹遍历

通用原则

• 导入后进行验证。 添加 2-3 个断言式检查，确认导入的数据符合预期。
• 导入文本和 Excel 数据时，始终设置 TextType="string"——与字符向量或字符向量元胞数组相比，string 类型效率更高，也更易于使用。仅需为带分隔符的文本和电子表格格式设置此项；XML、JSON 和其他格式默认已返回字符串。
• 从没有可识别扩展名的 URL 读取数据时，指定 FileType——MIME 类型检测可处理部分情况，但 API 端点和非标准 URL 仍需显式指定格式（参见主题 4）。将 detectImportOptions 与 readtable 搭配使用时，请在 detectImportOptions 上传入 FileType——提供导入选项对象时，readtable 不接受 FileType。
• 读取时处理缺失值占位符——在 readtable 中使用 TreatAsMissing，而非导入后调用 standardizeMissing。
• 直接读取压缩文件——readtable、readmatrix、readtimetable 和其他读取函数都可直接接受 ZIP、GZ 和 TAR 文件路径，无需手动解压（R2025a+）。
• 欧洲 CSV 使用 ; 作为分隔符，因为 , 是小数分隔符——当上下文线索表明数据采用欧洲格式时，同时设置 Delimiter 和 DecimalSeparator。

主题

1. 导入函数选择（分隔符和区域设置处理）

当上下文线索表明数据采用欧洲格式（德国／法国／意大利办公室、以分号分隔的文件、使用欧洲语言的列名）时，主动设置 Delimiter、DecimalSeparator 和 Encoding（变音符号／重音符号使用 UTF-8）：

opts = detectImportOptions("messdaten.csv", ...
    "Delimiter", ";", "DecimalSeparator", ",", "Encoding", "UTF-8");
T = readtable("messdaten.csv", opts);

对于包含路径类数据的文件（/data/exp_01/run_003/results.mat），明确设置实际分隔符——检测结果可能会从路径列中选取 /：

opts = detectImportOptions("fileList.csv");
opts.Delimiter = ",";
T = readtable("fileList.csv", opts);

对于带有内嵌单位后缀的数值数据（例如 6.53e+001dB、-9.00e+001°），请使用 TrimNonNumeric（R2022a+）剔除非数值字符，而不要使用 textscan 或 regexp：

T = readtable("circuit_output.txt", "Delimiter", {"\t", ","}, ...
    "NumHeaderLines", 1, "TrimNonNumeric", true);

可以将 TrimNonNumeric 直接作为名称-值对传递给 readtable；如果只有特定列带有后缀，也可以使用 setvaropts(opts, vars, "TrimNonNumeric", true) 按变量设置。

---

2. 错误消息解读

MATLAB I/O 错误消息可能比较笼统，指向一般类别而非具体问题：

错误消息	可能的实际原因	解决方法
"Entry may be password-protected or encrypted"	临时目录的磁盘空间不足，无法解压缩（在 R2020a–R2023b 中观察到）	使用 tempdir 检查可用空间；释放空间或重定向临时目录
"Unrecognized file extension"	URL 缺少可识别的文件扩展名	明确指定 FileType 名称-值对（参见主题 4）

---

3. 导入验证和数据保真度

从 Excel 或 Parquet 导入后，请检查是否发生静默数据损坏：

• Excel 中的 Inf → 65535：Inf 和 -Inf 都会写成 65535。看起来在物理上不合理、且恰好为 65535 的值可能代表 Inf。

• Excel 中的复数 → NaN：Excel 无法存储复数。电子表格中的整列 NaN 可能在源数据中包含复数。

• 含 null 的 Parquet 整数列 → 静默类型提升：当任意整数列（int8/16/32/64、uint8/16/32/64）包含 null 值时，parquetread 会将其提升为 double（MATLAB 整数类型没有缺失值表示）。对于 int64/uint64，超过 2^53 的值会静默丢失精度。可通过比较 parquetinfo 架构与 class(T.col) 来检测。解决方法：使用 parquetDatastore，设置 ReadSize="file"，再调用 readall；这样可以保留整数类型，并将 null 导入为 0。没有 null 时，所有整数类型通过 parquetread 往返读写都能保持精确。

• Excel 中的合并单元格 → 意外值：合并单元格会静默地产生重复值或缺失数据。使用 MergedCellColumnRule 和 MergedCellRowRule 控制解释方式：

T = readtable("report.xlsx", ...
    "MergedCellColumnRule", "placeleft", "MergedCellRowRule", "placetop");

缓解方法：写入 Excel 前，将复数拆分为实部／虚部列。

% Spreadsheet: check for Inf→65535 and complex→NaN
for i = 1:width(T)
    col = T.(T.Properties.VariableNames{i});
    if isnumeric(col) && all(isnan(col)) && height(T) > 0
        warning('Column "%s" is all-NaN — may contain complex numbers', ...
            T.Properties.VariableNames{i});
    end
    if isnumeric(col) && any(col == 65535)
        warning('Column "%s" contains 65535 — may represent Inf from Excel', ...
            T.Properties.VariableNames{i});
    end
end

% Parquet: detect null-triggered int64/uint64→double promotion (precision loss)
info = parquetinfo("data.parquet");
T = parquetread("data.parquet");
for i = 1:numel(info.VariableNames)
    if ismember(info.VariableTypes(i), ["int64","uint64"]) && isa(T.(info.VariableNames(i)), "double")
        warning('Column "%s" is %s in schema but double after read (nulls caused promotion)', ...
            info.VariableNames(i), info.VariableTypes(i));
    end
end

% Workaround: parquetDatastore preserves integer types (nulls become 0)
pds = parquetDatastore("data.parquet", "ReadSize", "file");
T = readall(pds);

筛选 Parquet 数据时，使用 rowfilter（R2022a+）将谓词下推到读取操作中——这样可避免将不需要的行加载到内存：

rf = rowfilter(["status", "age"]);
rf = rf.status == "active" & rf.age >= 18;
T = parquetread("users.parquet", "RowFilter", rf);

---

4. 从 URL 和 REST API 读取

始终明确指定 FileType——MATLAB 无法从 API 端点推断格式：

T = readtable("https://example.com/api/v2/export/measurements", "FileType", "text");

对于需要身份验证的端点，请使用 weboptions：

opts = weboptions("Timeout", 30, ...
    "HeaderFields", {"Authorization", "Bearer " + token});
diopts = detectImportOptions(url, "WebOptions", opts);
T = readtable(url, diopts);

---

5. readtable/writetable 模式

优先在读取时使用 TextType 和 TreatAsMissing，而不是在导入后使用 convertvars/standardizeMissing：

T = readtable("data.csv", "TextType", "string", "TreatAsMissing", "not applicable");

时间序列数据使用 readtimetable（R2019a+）——它会直接创建包含行时间的 timetable，避免单独执行 table2timetable 转换：

TT = readtimetable("sensor_log.csv", "RowTimes", "timestamp");

使用 readtable 直接读取表格型 JSON（R2026a+）——对于具有表格结构的 JSON 文件，使用 FileType="json"，而不是手动用 jsondecode 解析：

T = readtable("data.json", "FileType", "json");

直接从压缩归档文件读取，无需手动解压（R2025a+）：

T = readtable("data.csv.gz");
T = readtable("archive.zip/folder/data.csv");

使用 MissingRule 和 ImportErrorRule 控制导入时的错误处理（R2020b+），以便快速失败或省略错误行，而不是悄悄填入 NaN：

T = readtable("data.csv", "MissingRule", "error");
T = readtable("data.csv", "ImportErrorRule", "omitrow");

使用 struct2table + writetable 将结构体导出为 CSV——不要编写手动展开字段的循环：

T = struct2table(data.Results);
writetable(T, "results.csv");

writetable 会自动将向量值字段展开为带编号的列（例如，MemSet_1、MemSet_2）。对于 JSON/XML 输出，请改用 writestruct（参见主题 9）。

使用 writecell 导出元胞数组（R2019a+）——不要先转换为表：

writecell(results, "output.csv");

使用 readtable 直接读取表格型 XML——对于包含可映射为行的重复元素的 XML 文件，使用带有 RowNodeName（以及可选的 TableNodeName）的 readtable，而不是手动解析 DOM：

T = readtable("measurements.xml", ...
    "TableNodeName", "measurements", "RowNodeName", "measurement");

---

6. 文本文件 I/O：使用 readlines/writelines 替代 fopen 模式（R2020b+）

简单文本文件 I/O 优先使用 readlines/writelines——读取或写入整个文件作为字符串数组时，避免使用 fopen/fgetl/fprintf/fclose：

% Reading: readlines returns a string array — no file handles needed
lines = readlines("config.txt");
matches = lines(contains(lines, "keyword"));

% Writing: writelines handles string arrays directly
messages = ["Starting process"; "Step 1 complete"; "Done"];
writelines(messages, "output.log");

% Line-by-line processing: read all then operate vectorially
lines = readlines("events.log");
lines = lines(lines ~= "");  % remove empties
parts = split(lines, "|");   % vectorized split
timestamps = parts(:,1);
levels = parts(:,2);

fopen/fgetl 循环模式已过时——readlines 更简单，能妥善处理空文件，还能对整个文件一次性执行向量化字符串操作。

---

7. XML I/O：使用 MAXP 替代 JAXP

对所有 XML 操作使用 MAXP 提供程序（R2024b+）——它完全由 MATLAB 实现，无需 Java：

% Reading XML with MAXP
import matlab.io.xml.dom.*
doc = parseFile(Parser, "settings.xml");
params = getElementsByTagName(doc, "parameter");
for i = 1:params.Length
    node = params.item(i);
    name = getAttribute(node, "name");
    value = getAttribute(node, "value");
end

% Writing XML with MAXP
import matlab.io.xml.dom.*
doc = Document("testResults");
root = getDocumentElement(doc);
for i = 1:height(T)
    tc = createElement(doc, "testcase");
    setAttribute(tc, "name", T.test_name(i));
    setAttribute(tc, "status", T.status(i));
    appendChild(root, tc);
end
xmlwrite("results.xml", doc);

不要使用旧版 JAXP 接口（com.mathworks.xml.XMLUtils.createDocument、对 Java DOM 对象调用 getElementsByTagName、使用基于 0 的 item() 索引调用 getAttribute）。MAXP 完全由 MATLAB 实现，无需 Java。

---

8. 使用非标识符键的 JSON（R2024b+）

当 JSON 键包含空格、连字符或其他不符合 MATLAB 标识符规则的字符时，请使用 dictionary，而不是 struct：

d = readdictionary("config.json");
val = d("my-custom-key");
d("new key with spaces") = 42;
writedictionary(d, "config.json");

jsondecode 会将此类键转换为有效标识符（例如，my_custom_key），导致往返转换时丢失原始键名。readdictionary/writedictionary 会准确保留键名。

---

9. 结构体 I/O：使用 readstruct/writestruct 替代 jsondecode/xmlread（XML 适用于 R2020b+，JSON 适用于 R2023b+）

基于结构体进行文件 I/O 时使用 readstruct/writestruct——当目标是获取结构体时，不要使用 fileread+jsondecode 或 xmlread+DOM 遍历：

% Reading JSON into a struct
config = readstruct("app_config.json");
host = config.database.host;

% Writing a struct to JSON
writestruct(config, "output_config.json");

% Reading XML into a struct
params = readstruct("device_config.xml");
rate = params.sensor.rate;

% Writing a struct to XML
writestruct(params, "params.xml");

readstruct/writestruct 可通过一次调用处理 JSON 和 XML，同时保留嵌套字段结构。避免使用旧模式：JSON 使用 fileread+jsondecode/jsonencode+fopen+fwrite，XML 使用 xmlread+getElementsByTagName+getAttribute。

---

Copyright 2026 The MathWorks, Inc.