Spark 读取本地文件这件事，说简单也简单，spark.read.text一行就能跑通；说坑多也是真的多，尤其是当你从单机模式切到集群模式、从local模式切到yarn模式的时候，同一段代码昨天还能读D:/data/xxx.csv，今天换个环境就报FileNotFoundException，或者更隐蔽的——文件明明读到了，但只有一部分数据，剩下的被静默丢掉了。这篇内容就围绕"Spark 读取本地文件"这个看似基础的动作，把路径语义、file://与默认文件系统的区别、分区读取、编码与格式处理、以及集群环境下本地文件到底"本地"在哪台机器上这些容易翻车的点，一次讲透。
适合谁看：刚上手 Spark、习惯用local[*]跑脚本的同学；正在把单机脚本往集群迁移、被路径问题卡住的同学；以及想搞清楚spark.read背后到底发生了什么、不想再靠试错来调参的同学。下面所有结论都来自实际跑任务时踩出来的经验，代码可以直接抄，但环境相关的部分我会标清楚前提，你按自己的集群情况对号入座。
1. 先搞清楚"本地文件"在 Spark 里到底指谁的文件
很多人第一次被 Spark 的"本地文件"坑到，是因为脑子里默认"本地 = 我这台开发机"。这个默认在local模式下成立，一旦提交到集群就不成立了。Spark 是分布式计算框架，Driver 和 Executor 可能跑在不同机器上，你写的那个路径字符串会被分发到各个 Executor 上去解析，每个 Executor 都在自己的机器上找这个路径。所以"读取本地文件"这件事，第一件要确认的不是 API 怎么写，而是这个文件对谁来说是本地的。
1.1 Driver 本地、Executor 本地，是两个完全不同的概念
在local[*]模式下，Driver 和 Executor 在同一个 JVM 进程里（严格说是同一个进程内的不同线程），此时你写的相对路径或绝对路径，解析的基准就是启动这个进程的那台机器的工作目录。所以你在 IDE 里跑spark.read.csv("data/test.csv")，它找的是项目根目录下的data/test.csv，能跑通，很自然。
但换成spark-submit --master yarn提交后，Driver 可能在某台节点上，Executor 分散在另外若干台节点上。你代码里写的data/test.csv会被每个 Executor 用自己的工作目录去解析。结果就是：Driver 那台机器上有这个文件，但 Executor 那台没有，任务报FileNotFoundException；或者更巧的情况，某几台 Executor 上恰好有同名文件，于是你读到的数据一半对一半错，这种问题排查起来极其折磨。
我见过一个很典型的场景：某同学在本地用local模式开发，数据放在项目里的resources目录，测试全绿。上线到集群后，他把 jar 打上去，路径没改，结果任务一直失败。他以为是权限问题，查了半天，最后发现是 Executor 的工作目录里根本没有那个文件——文件被打进 jar 了，但 Spark 读的是文件系统路径，不是 classpath 资源。这个区分很关键：classpath 资源和文件系统路径是两套东西，spark.read走的是后者。
1.2 相对路径的解析基准，比你想的更不稳定
相对路径在 Spark 里是个雷区。它的解析基准取决于当前工作目录（user.dir），而这个值在不同提交方式下是不一样的：
| 提交方式 | 相对路径解析基准 | 稳定性 |
|---|---|---|
| IDE 本地运行 | 项目根目录 | 较稳定，但换 IDE 可能变 |
spark-submitlocal 模式 | 执行命令时所在目录 | 取决于你在哪敲命令 |
spark-submit集群模式 | Executor 进程的工作目录 | 基本不可控 |
| 客户端模式 + 集群 | Driver 所在机器目录 | 取决于部署方式 |
所以我的建议很直接：只要不是纯本地练手，路径一律写绝对路径，并且显式带上file://前缀。相对路径省的那几个字符，换来的是排查两小时的代价，不划算。
1.3file://前缀不是可有可无的装饰
这里要展开讲一个高频误解。Spark 的路径解析会经过 Hadoop 的FileSystem抽象层，如果你不写 scheme，它会用fs.defaultFS配置的默认文件系统来解析。在典型的 Hadoop 集群里，fs.defaultFS是hdfs://namenode:8020，也就是说，你写/data/test.csv，Spark 会去 HDFS 的根目录下找，而不是本地磁盘的/data/test.csv。
这就是为什么很多人明明本地有文件，却报"文件不存在"——它压根没去本地找。加上file://前缀，等于明确告诉 Spark："别用默认文件系统，就用本地文件系统"。写法上：
# 明确指定本地文件系统 df = spark.read.csv("file:///data/test.csv", header=True) # 不写 scheme，走 fs.defaultFS，集群里大概率是 HDFS df = spark.read.csv("/data/test.csv", header=True)注意file:///是三个斜杠：file://是 scheme 加空 authority，后面接绝对路径/data/test.csv，合起来就是file:///data/test.csv。写成file://data/test.csv会被解析成 authority 为data的路径，行为很怪，别这么写。
2. 不同读取 API 的选型：text、csv、json 到底该用哪个
路径搞清楚了，接下来是选 API。Spark 的spark.read下面挂了一堆方法，text、csv、json、parquet、orc，还有通用的format().load()。选错 API 不会报错，但会给你一个结构完全不对的 DataFrame，后面处理起来全是麻烦。
2.1text是最"裸"的读取方式，也是最不容易出错的
spark.read.text()的行为非常朴素：一行文本就是一行记录，整个 DataFrame 只有一列，列名默认叫value，类型是 string。它不做任何解析、不做任何类型推断、不关心分隔符。这种"什么都不管"的特性，反而让它在很多场景下是最稳的选择。
什么时候用text？我的经验是：当你只想拿到原始行、后续要用 UDF 或正则自己解析的时候。比如日志文件、非标准分隔符的文本、需要按行做复杂字符串处理的场景。用text读进来，拿到干净的原始行，再自己写解析逻辑，比让csv去猜分隔符、猜引号、猜转义要可控得多。
# 读原始文本，每行一条记录，单列 value raw = spark.read.text("file:///data/app.log") raw.show(5, truncate=False) # 后续自己解析，比如按空格切分取前几个字段 from pyspark.sql.functions import split, col parsed = raw.select(split(col("value"), "\\s+").alias("parts"))这里有个细节值得说：text读取时，如果文件是 UTF-8 之外的编码（比如 GBK），读进来会是乱码。text默认按 UTF-8 解码，没有直接的 encoding 参数（老版本没有，新版本部分场景可以通过 Hadoop 配置调，但很绕）。遇到 GBK 文件，稳妥做法是先转码成 UTF-8 再读，或者用spark.sparkContext.textFile配合自定义 Hadoop 配置。这个后面第 4 节会展开。
2.2csv的自动推断是个双刃剑
spark.read.csv用起来最爽的地方是inferSchema=True，它会扫一遍数据自动推断每列类型。但这个"爽"是有代价的：它需要额外扫一遍数据，对大文件来说等于读了两遍，性能直接翻倍。而且推断结果不一定符合你的预期，比如一列全是数字但有一行是空字符串，它可能推断成 string；再比如前几行是整数、后面出现小数，它可能推断成 double 导致精度问题。
我的做法是：生产环境永远显式指定 schema，不用 inferSchema。显式 schema 有两个好处，一是省掉那一遍扫描，二是类型完全可控，不会因为数据里混进脏值就整体降级成 string。写法：
from pyspark.sql.types import StructType, StructField, StringType, IntegerType, DoubleType schema = StructType([ StructField("id", IntegerType(), False), StructField("name", StringType(), True), StructField("score", DoubleType(), True), ]) df = spark.read.csv( "file:///data/students.csv", header=True, schema=schema, sep=",", quote='"', escape='"', nullValue="", mode="PERMISSIVE" )几个参数值得单独说。nullValue=""表示空字符串当 null 处理，不写的话空串会被当成空字符串而不是 null，后续isNull判断会失效。mode控制脏行处理策略，PERMISSIVE是遇到坏行放一个全 null 的记录进去，DROPMALFORMED是直接丢掉坏行，FAILFAST是遇到坏行立刻报错。调试阶段用 FAILFAST，能第一时间暴露数据问题；生产环境用 PERMISSIVE 或 DROPMALFORMED，避免一条脏数据搞挂整个任务。这个策略选择很多人不重视，结果线上因为一行格式错误的数据导致整个批次失败，回滚重跑，很冤。
2.3json读取对"一行一个 JSON"有硬性要求
spark.read.json默认要求每行是一个完整的 JSON 对象，不是格式化的多行 JSON，也不是 JSON 数组。如果你拿到的是一个[{...}, {...}]这样的数组文件，直接read.json会解析失败或者读出一堆 null。这种情况要么先用text读进来再from_json解析，要么用multiLine=True参数（这个参数对内存有要求，大文件慎用）。
# 标准的一行一 JSON df = spark.read.json("file:///data/events.jsonl") # 整个文件是一个 JSON 数组的情况 df = spark.read.option("multiLine", True).json("file:///data/array.json")multiLine=True的原理是把整个文件当一个 JSON 文档解析，这意味着文件必须能完整放进单个 Executor 的内存，大文件会 OOM。所以这个参数只适合小配置文件类的场景，数据文件还是老老实实转成行式 JSON。
2.4 格式选型速查
| API | 适用场景 | 主要坑点 |
|---|---|---|
text | 原始日志、自定义解析 | 编码固定 UTF-8，无 schema |
csv | 结构化表格数据 | 分隔符/引号推断、inferSchema 性能 |
json | 半结构化、一行一对象 | 多行 JSON 需 multiLine，内存敏感 |
parquet | 列式存储、生产首选 | 本地文件场景较少，多为 HDFS |
format().load() | 通用入口、自定义数据源 | 参数传递容易写错 |
3. 分区读取与文件通配：一个路径背后的文件数量陷阱
这是我认为"读取本地文件"里最容易被低估的一块。很多人以为给一个路径就是读一个文件，实际上 Spark 的路径参数支持通配符和目录，给一个目录它会读目录下所有文件，给一个通配符它会匹配一批文件。这个特性用好了很方便，用不好就是数据翻倍或者漏读。
3.1 给目录 vs 给文件，行为差异很大
当你给spark.read.csv("file:///data/input/")一个目录时，Spark 会读取该目录下所有符合格式的文件，并且把它们合并成一个 DataFrame。这里有几个隐含行为：
第一，它会跳过以_和.开头的文件。这是 Hadoop 的约定，_SUCCESS、.crc这类元数据文件不会被当成数据读进来。这个设计很贴心，但如果你自己的数据文件恰好以_开头，就会被静默忽略，排查时容易懵。
第二，它默认不递归读子目录。目录下如果有子目录，子目录里的文件不会被读。要递归得显式开recursiveFileLookup：
df = spark.read.option("recursiveFileLookup", True).csv("file:///data/input/")第三，多个文件的 schema 会做合并。如果不同文件的列不一致，Spark 会取并集，缺失的列填 null。这个行为在数据来源不统一时很有用，但也可能掩盖数据质量问题——你以为读到了完整数据，其实某些文件缺列，读进来全是 null。
3.2 通配符匹配的边界
路径里可以用*匹配任意字符，用?匹配单个字符，用[abc]匹配字符集。比如file:///data/2024-*.csv能匹配所有 2024 年开头的 csv。但要注意，通配符是在 Driver 端展开的，展开后得到文件列表再分发给 Executor。如果匹配到的文件特别多（比如几万个），Driver 端展开列表本身就会成为瓶颈，甚至 OOM。这种场景应该改用分区目录结构，让 Spark 按分区裁剪，而不是靠通配符硬匹配。
还有一个坑：通配符匹配到 0 个文件时，不同版本行为不一致。有的版本直接报错，有的版本返回空 DataFrame。如果你依赖"读不到就报错"来发现问题，最好在读完之后加一个df.rdd.isEmpty()的检查，或者用spark.read.csv(...).count()确认非零。
3.3 小文件问题在本地读取时同样存在
"小文件问题"通常被认为是 HDFS 上的事，其实本地读取一样会遇到。假设你有一个目录，里面是 1000 个几 KB 的小文件，spark.read.csv读进来后，这 1000 个文件会对应多少个分区？默认情况下，Spark 按文件切分，每个文件至少一个分区（如果文件小于 block size）。1000 个小文件就是 1000 个分区，每个分区启动一个 task，task 启动开销远大于处理这几 KB 数据的开销，整体慢得离谱。
解决办法是在读取后立刻repartition或coalesce合并分区：
df = spark.read.csv("file:///data/many_small_files/") # 合并到合理分区数，比如按数据量估算 df = df.coalesce(8)coalesce是窄依赖，不 shuffle，适合减少分区；repartition是宽依赖，会 shuffle，适合增加分区或打散数据。小文件合并场景用coalesce就够了。分区数怎么定？一个经验值是每个分区处理 128MB 到 256MB 数据，你可以先df.rdd.getNumPartitions()看当前分区数，再结合数据总量估算。
4. 编码、压缩与特殊格式：那些让读取"看起来成功实则出错"的细节
前面讲的都是路径和结构层面的问题，这一节讲数据内容层面的坑。这类问题的特点是：任务不报错，DataFrame 也有数据，但内容是错的。比报错更难排查，因为你的注意力根本不在读取环节。
4.1 编码问题：UTF-8 之外的文本怎么读
Spark 的text和csv默认按 UTF-8 解码。如果你的文件是 GBK 编码（国内很多老系统导出的 CSV 就是 GBK），读进来中文全是乱码。这个问题在csv上尤其隐蔽，因为乱码的字符串依然是合法的 string，不会报错，你只有show()出来看到一堆问号或方块才会发现。
处理方式有几种，按推荐程度排序：
第一种，源头转码。用系统工具或脚本把文件转成 UTF-8 再喂给 Spark。这是最干净的做法，一次转码，后续所有读取都省心。命令行用iconv -f GBK -t UTF-8 input.csv > output.csv就行。
第二种，通过 Hadoop 配置指定编码。spark.read.text底层走的是TextInputFormat，可以通过spark.hadoop.mapreduce.input.fileinputformat相关配置或者自定义Configuration来改编码，但这条路比较绕，不同 Spark 版本行为还不一致，我不太推荐在生产里用。
第三种，用binaryFile读原始字节再自己解码。这个方式最灵活，适合编码混杂、无法统一转码的场景：
# 读原始字节，自己按指定编码解码 df = spark.read.format("binaryFile").load("file:///data/gbk_file.csv") df = df.select( df.content.cast("string").alias("raw") # 注意：cast 仍按 UTF-8，需配合 UDF )实际上binaryFile读进来的是content二进制列，要正确解码 GBK 得用 Python UDF 调bytes.decode("gbk")，性能有损耗，只适合小数据量或必须精确处理的场景。
4.2 压缩文件：能读，但分区数会变
Spark 支持直接读.gz、.bz2、.zip等压缩格式，spark.read.csv("file:///data/data.csv.gz")能正常工作。但有个关键限制：gzip 这类压缩格式不可切分（non-splittable），一个 gz 文件只能由一个 task 完整读取，无法并行。所以如果你有一个 10GB 的 gz 文件，读取阶段就是单 task 处理 10GB，慢且容易 OOM。
这个特性带来的直接后果是分区数计算方式变了。普通文本文件按 block size 切分，一个 1GB 文件可能切成 8 个分区；但一个 1GB 的 gz 文件只有 1 个分区。如果你后续操作依赖分区数（比如并行度调优），这个差异必须考虑进去。解决办法是读完后主动repartition打散，或者源头就别用 gz，改用支持切分的格式（如 parquet 配合 snappy 压缩，snappy 块是可切分的）。
4.3 空文件与只有表头的文件
一个目录里混着空文件和正常文件是常见情况。空文件（0 字节）读进来不产生任何行，不影响结果，但会在文件列表里占一个位置。只有表头没有数据的文件，在header=True时会被正确识别为 0 行数据，也不影响。真正麻烦的是表头不一致：不同文件的表头列名或列顺序不同，Spark 按位置合并，列名取第一个文件的，后面的文件如果列顺序不一样，数据就会错位。
这种问题不会报错，只会让你拿到一列"看起来是分数其实是年龄"的数据。防御手段是读取时显式给 schema（按位置匹配，不依赖表头），或者读之前先校验所有文件的表头一致性。我一般会在读取前跑一个轻量的预检脚本，把所有文件的表头抽出来比对，不一致就报警，别等到下游算出离谱结果才发现。
5. 集群环境下读本地文件的正确姿势与替代方案
前面反复提到集群模式下本地文件的坑，这一节集中讲怎么在集群环境里正确处理"本地文件"这个需求。核心结论先给：集群里读本地文件，要么保证文件在所有节点上都有，要么就别用本地文件系统，改用共享存储。
5.1 文件分发：--files参数的正确用法
spark-submit提供了--files参数，可以把本地文件分发到集群各节点。用法：
spark-submit \ --master yarn \ --files /local/path/config.json,/local/path/lookup.csv \ app.py分发后，Executor 可以通过文件名直接访问（Spark 会把文件放到每个 Executor 的工作目录，并设置好相对路径）。代码里读的时候用文件名而不是绝对路径：
# 分发后的文件，用文件名访问 df = spark.read.csv("lookup.csv", header=True)但--files有几个限制要知道：它适合小文件（配置文件、维表），大文件分发会拖慢启动且占用各节点磁盘；分发是一次性的，任务运行期间文件不会更新；而且它分发到的是 Executor 的工作目录，不是所有路径都能访问。所以--files的定位是"小配置分发"，不是"大数据传输"。
5.2 共享存储才是集群读文件的正解
如果数据量大、需要多节点访问，正确做法是把文件放到所有节点都能访问的共享存储上。常见选择：
| 存储类型 | 适用场景 | 注意点 |
|---|---|---|
| 分布式文件系统 | 大数据量、生产环境 | 需要集群已部署，路径带 scheme |
| 网络共享挂载 | 中小规模、过渡期 | 挂载点需所有节点一致 |
| 对象存储 | 云环境、弹性扩展 | 需配置对应 connector 和凭证 |
以分布式文件系统为例，把文件先上传上去，然后读取时用对应 scheme 的路径：
# 上传到分布式文件系统后读取 df = spark.read.csv("hdfs:///data/input/test.csv", header=True)这里的关键认知转变是："读取本地文件"在集群语境下，本质是一个反模式。本地文件系统的设计前提是单机访问，而 Spark 的设计前提是分布式访问，两者天然冲突。真正该做的不是想办法让集群读本地文件，而是把数据放到分布式存储上，让"本地"这个概念消失。
5.3 什么时候确实需要读本地文件
也不是所有集群场景都要避开本地文件。有两种情况是合理的：
第一种，Driver 端读取小文件做广播。比如一个几百行的维表，可以在 Driver 端用普通 Python 读进来，然后broadcast出去，避免每个 Executor 都去读一遍。这种场景文件只在 Driver 机器上，用普通文件读取 API 而不是spark.read：
# Driver 端读小文件，广播出去 with open("/local/path/lookup.json") as f: lookup = json.load(f) bc = spark.sparkContext.broadcast(lookup)第二种，local模式下的开发调试。这时候本地文件就是唯一选择，按第 1 节的建议用绝对路径加file://前缀即可。
除了这两种，其他"集群读本地文件"的需求，我都建议重新审视：是不是数据放错地方了？是不是该用共享存储？把这个问题想清楚，能省掉大量排查时间。
6. 几个真实踩坑的排查链路
光讲原理不够，这一节还原几个我实际遇到的排查过程，重点不是结论，而是怎么一步步定位到根因，这个思路比结论更有复用价值。
6.1 案例一：本地能跑，集群报文件不存在
现象：IDE 里local模式跑得好好的，spark-submit到集群后报FileNotFoundException: /data/test.csv。
排查链路：第一步，看报错里的路径是/data/test.csv，没有 scheme。这说明 Spark 用的是默认文件系统去解析，而集群的fs.defaultFS大概率是分布式文件系统，所以它去分布式文件系统的根目录找，当然找不到。第二步，确认代码里写的是相对路径还是绝对路径，发现是/data/test.csv这种"看起来像绝对路径但没 scheme"的写法。第三步，改成file:///data/test.csv再跑，报错变成"Executor 上文件不存在"——这印证了第 1 节的结论，路径解析到了本地，但 Executor 那台机器上没有这个文件。第四步，确认文件只在 Driver 机器上，最终方案是把文件上传到共享存储，路径改成对应 scheme。
这个案例的教训是：报错信息里的路径有没有 scheme，是判断解析目标的第一线索。看到没 scheme 的路径报不存在，先怀疑默认文件系统，别急着查权限。
6.2 案例二：数据读到了，但少了一大半
现象：读一个目录下的 csv，count()出来的行数比预期少很多，但没有任何报错。
排查链路：第一步，手动ls目录，数文件个数和总行数，确认预期值。第二步，用df.inputFiles()看 Spark 实际读了哪些文件，发现少读了几个。第三步，看少读的文件名，发现它们以_开头——正是第 3.1 节说的，Spark 默认跳过_和.开头的文件。第四步，确认这些文件确实是数据文件而非元数据，于是改名去掉下划线前缀，重新读取，行数对上。
这个案例的教训是：行数不对但没报错，第一反应应该是inputFiles()看读了哪些文件，而不是怀疑数据本身。inputFiles()这个方法在排查读取问题时极其有用，建议养成习惯。
6.3 案例三：中文全是乱码，但任务成功
现象：读一个 csv，任务成功，但show()出来中文列全是乱码。
排查链路：第一步，确认文件编码，用file -i命令看，发现是 GBK。第二步，确认 Spark 读取默认编码是 UTF-8，两者不匹配。第三步，评估方案：文件不大，直接iconv转成 UTF-8 最省事。第四步，转码后重读，乱码消失。
这个案例的教训是：乱码不报错，所以要在读取后主动校验。我的习惯是在读取关键数据后，抽样show()几行看看内容是否合理，尤其是含中文的列。这个动作花不了几秒，但能提前发现编码、分隔符错位这类静默问题。
6.4 案例四：gz 文件读取慢到怀疑人生
现象：读一个 5GB 的.csv.gz，任务卡在读取阶段很久，且只有一个 task 在跑。
排查链路：第一步，看 Spark UI，发现读取阶段只有一个 task，其他 Executor 空闲。第二步，回忆 gz 不可切分的特性，确认这是单文件单 task 的典型表现。第三步，评估方案：如果源头能改，换成可切分格式；如果改不了，读完后repartition打散后续计算。第四步，实测repartition(16)后，后续聚合阶段并行度上来了，整体耗时下降明显。
这个案例的教训是：压缩格式的可切分性直接影响并行度，选压缩格式时不能只看压缩率，还要看是否支持切分。gzip 压缩率高但不可切分，适合归档不适合计算；snappy 压缩率低但可切分，适合计算场景。
7. 一份可以直接抄的读取配置模板
讲了这么多坑，最后给一份我日常用的读取模板，覆盖了大部分防御性配置。你可以根据自己的场景裁剪，但建议保留注释里标了"建议保留"的项。
from pyspark.sql.types import StructType, StructField, StringType, IntegerType, DoubleType # 1. 显式 schema，避免 inferSchema 的额外扫描和类型漂移 schema = StructType([ StructField("id", IntegerType(), False), StructField("name", StringType(), True), StructField("amount", DoubleType(), True), ]) df = ( spark.read .option("header", True) # 有表头 .option("sep", ",") # 显式分隔符，别让它猜 .option("quote", '"') # 引号字符 .option("escape", '"') # 转义字符 .option("nullValue", "") # 空串当 null，建议保留 .option("mode", "FAILFAST") # 调试期用 FAILFAST，生产改 PERMISSIVE .option("encoding", "UTF-8") # 显式编码，建议保留 .schema(schema) .csv("file:///data/input/") # 绝对路径 + file:// 前缀 ) # 2. 读取后校验：文件列表和行数 print("读取的文件:", df.inputFiles()) print("总行数:", df.count()) # 3. 小文件场景合并分区 # df = df.coalesce(8)几个使用要点再强调一遍。mode在调试期一定用FAILFAST，让脏数据第一时间暴露，别等跑完整个流程才发现问题；生产环境根据容忍度选PERMISSIVE或DROPMALFORMED，但无论选哪个，都要配套监控坏行数量，别让脏数据静默累积。inputFiles()和count()这两个校验动作建议固化成习惯，读取环节的问题九成能靠这两个动作提前发现。
另外，如果你读的是本地文件且数据量不大，可以在读取后立刻cache()，避免后续多次 action 重复读盘：
df = df.cache() df.count() # 触发缓存但cache()要配合unpersist()使用，用完及时释放，否则会一直占着内存。这个习惯在长时间运行的任务里尤其重要。
最后分享一个我自己的体会：Spark 读取本地文件这件事，技术难度不高，难的是建立正确的环境认知。同样一行spark.read.csv(path)，在local模式和集群模式下语义完全不同，在有无 scheme 时解析目标完全不同，在文件是普通文本还是压缩包时并行度完全不同。把这些"不同"搞清楚，比记住多少个 API 参数都有用。我现在的习惯是，每换一个运行环境，先用一个最小文件跑一遍读取，确认路径解析、编码、分区数都符合预期，再上真实数据。这个前置验证花五分钟，能省掉后面几小时的排查。
