38 exftp-FTP客户端
作者:魏健强 | 最后修改:2026-11-17
一、概述
exftp 是 LuatOS 提供的 FTP 客户端 扩展库。它基于核心库 socket 实现,用纯 Lua 写成,封装了 FTP 协议的登录、目录切换、文件上传和文件下载流程,让用户不必自己处理 FTP 的命令通道、数据通道和响应码解析。
它的工作方式是这样的:
- 命令通道:
exftp.create()建立一条到 FTP 服务器 21 端口的 TCP 连接,之后的USER、PASS、PWD、CWD、STOR、RETR、SIZE等命令和服务器响应都走这条连接。 - 数据通道:真正传输文件内容时,库会先用
PASV命令让服务器开启一个临时端口,再由设备主动连上去,这就是 被动模式。传完数据后关闭数据通道,服务器再通过命令通道回226表示传输完成。 - 分块传输:上传时以缓冲区大小为单位反复"读取本地文件 →
socket.tx发送 → 等 TX_OK",缓冲区默认 128 KB,内存不足时按 64 KB → 24 KB → 8 KB 逐级降级;下载时按数据通道的接收事件流式写入本地文件,不会把整个文件读进内存,因此适合传几 MB 到几十 MB 的文件。
本库支持的能力
- 连接与登录(
create/auth) - 上传文件(
upload)、下载文件(download) - 切换目录(
chdir)、查询当前目录(pwd)、返回上级目录(cdup) - 操作日志开关(
debug)、关闭连接(close)、查看库版本(version)
本库不支持的能力(使用前请注意)
- 不能列目录:库内没有封装
LIST/NLST,拿不到服务器上的文件列表,文件名必须由用户自己知道。 - 不能建目录、删文件、改文件名:没有
MKD、RMD、DELE、RNFR/RNTO。 - 不支持断点续传:没有
REST、APPE。 - 不支持主动模式:只走
PASV,服务器若只允许PORT主动模式则无法传输。 - 不支持 FTPS / SFTP:这是明文 FTP 客户端,不带 TLS 加密,也没有 SSH 通道。
依赖的核心库
exftp 依赖 socket(网络)、io(文件读写)、zbuff(收发缓冲区)、sys(协程与消息),这四者都是 LuatOS 标配核心库,不需要额外配置固件。
使用前必须做的一件事
exftp 属于 Lua 脚本库,源码在 LuatOS 仓库的 script/libs/exftp.lua,它不会被编进固件。使用前需要把这个文件复制到你自己的项目里(通常放在项目的 libs/ 目录,或者直接和 main.lua 同级),再用 require "exftp" 引入。如果只写 require "exftp" 而没有放文件,运行时会报找不到模块。
和核心库 ftp 的关系与区别
LuatOS 里其实有 两套 FTP 客户端,不要混淆:
| 对比项 | 核心库 ftp | 扩展库 exftp(本页) |
|---|---|---|
| 实现方式 | C 代码,编进固件 | 纯 Lua 脚本,随项目分发 |
| 使用方法 | 固件支持时全局就有 ftp 表,直接 ftp.login() |
需要 require "exftp" |
| 接口风格 | 平铺函数:login / command / pull / push / close / debug |
先 create() 拿实例,再用 实例:方法() |
| 上传下载 | ftp.push(本地, 远端) / ftp.pull(本地, 远端) |
ftpc:upload(本地, 远端, opts) / ftpc:download(远端, 本地, opts),下载时远端在前 |
| 目录操作 | 没有专门接口,要用 ftp.command("CWD xxx") 发原始命令 |
chdir() / pwd() / cdup() 已封装 |
| 依赖固件 | 依赖固件是否打开 LUAT_USE_FTP(主流固件默认已打开,IMS/VoLTE 类特殊配置会关闭) |
只要固件有 socket/io/zbuff 就能跑,换固件不用改代码 |
| 版本查询 | 与固件版本绑定 | exftp.version() 查脚本库版本 |
怎么选:固件里已经能用 ftp 表、业务也只是简单传个文件,用核心库 ftp 更省事,不需要往项目里塞文件;如果当前固件的 ftp 是 nil(固件没开 LUAT_USE_FTP),或者需要频繁切目录、想让传输逻辑跟着项目走、换固件不受影响,就用 exftp。
二、核心示例
1、核心示例是指:使用本库文件提供的核心 API,开发的基础业务逻辑的演示代码;
2、核心示例的作用是:帮助开发者快速理解如何使用本库,所以核心示例的逻辑都比较简单;
3、更加完整和详细的 demo,请参考 LuatOS 仓库 中的自动化测试用例,它在一块板子上轮询测试了 4G 网卡、WiFi 网卡和默认网卡三种适配器。
--[[
本核心示例的业务逻辑为:
1、等待网络就绪;
2、创建 FTP 客户端并登录;
3、查看当前目录,上传一个本地文件,再把它下载回来;
4、关闭连接。
]]
-- 引入 exftp 库(需先把 LuatOS/script/libs/exftp.lua 复制到本项目的 libs 目录)
local exftp = require "exftp"
-- FTP 服务器参数,请换成你自己的服务器
local FTP_HOST = "121.43.224.154"
local FTP_PORT = 21
local FTP_USER = "ftp_user"
local FTP_PASS = "3QujbiMG"
sys.taskInit(function()
-- 1. 等待获取到 IP,否则 socket.create 会直接失败
while not socket.adapter(socket.dft()) do
log.warn("ftp", "wait IP_READY", socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- 2. 创建客户端。第一个参数 adapter 传 nil 表示使用当前默认网卡,
-- 想指定网卡可以传 socket.LWIP_GP(4G)或 socket.LWIP_STA(WiFi)
local ftpc = exftp.create(nil, FTP_HOST, FTP_PORT)
if not ftpc then
log.error("ftp", "创建 FTP 客户端失败")
return
end
-- 3. 登录
if not ftpc:auth(FTP_USER, FTP_PASS) then
log.error("ftp", "登录失败")
ftpc:close()
return
end
-- 4. 查询当前目录(返回 true, "/path")
local ok, dir = ftpc:pwd()
log.info("ftp", "当前目录", ok, dir)
-- 5. 上传:先造一个本地文件
io.writeFile("/test_upload.txt", "hello luatos " .. os.date())
local up_ok = ftpc:upload("/test_upload.txt", "/test_upload.txt", { timeout = 60 * 1000 })
log.info("ftp", "上传结果", up_ok)
-- 6. 下载:把刚上传的文件拉回来,落到另一个文件名
local down_ok = ftpc:download("/test_upload.txt", "/downloaded.txt", { timeout = 30 * 1000 })
log.info("ftp", "下载结果", down_ok, "本地大小", io.fileSize("/downloaded.txt"))
-- 7. 关闭连接(内部会先关数据通道,再关命令通道)
ftpc:close()
end)
三、常量详解
本库 不对外导出任何常量,不要写 exftp.常量名 这种形式,没有可用的取值,下面的两组数值是库内部使用的,列出来只是为了帮助你看懂串口日志,不要在业务代码里直接使用。
3.1 内部连接状态(STATE)
| 数值 | 含义 | 什么时候处于该状态 |
|---|---|---|
| 0 | 未连接 | create() 刚开始,或已经调用过 close() |
| 1 | 已连接未认证 | 命令通道已建立并且收到服务器 220 服务就绪响应 |
| 2 | 已认证 | auth() 成功之后,可以正常收发命令 |
| 3 | 传输中 | upload() / download() 正在收发数据,传完自动回到 2 |
这些状态由库自己维护,用户代码不需要读写。唯一有实际意义的是:除了 create(),其它所有方法都要求当前状态是"已认证",否则直接返回 false——所以忘记调 auth() 或 close() 之后再调 pwd(),看到的都是 false。
3.2 内部使用的 FTP 响应码
| 响应码 | 含义 | 库里的用途 |
|---|---|---|
| 213 | 文件状态 | download() 前用 SIZE 取远端文件大小 |
| 220 | 服务就绪 | create() 判断服务器是否可用 |
| 226 | 传输完成 | upload() / download() 结束前等待的收尾响应 |
| 227 | 进入被动模式 | PASV 成功,响应里带数据通道的 IP 和端口 |
| 230 | 登录成功 | auth() 发送 PASS 之后的成功响应 |
| 250 | 文件操作成功 | chdir() / cdup() 成功的响应 |
| 257 | 路径名已创建 | pwd() 成功的响应,路径在引号里 |
| 331 | 用户名正确,需要密码 | auth() 发完 USER 之后,继续发 PASS |
| 150 | 数据连接已打开 | STOR / RETR 被接受,即将开始传输 |
| 125 | 数据连接已打开 | 同上,部分服务器用 125 代替 150 |
传输命令的响应,库接受 150、125、250 三种;226 是传输结束的标志。看日志时如果只看到 150 没有 226,通常是数据通道没关掉或者网络断了。
四、函数详解
4.1 exftp.create(adapter, host, port)
功能
创建一个 FTP 客户端实例,并完成到服务器的 TCP 连接、等待服务器回 220 服务就绪响应。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| adapter | number/nil | 否 | 网络适配器序号。传 nil 表示使用当前默认网卡(即 socket.dft() 的返回值);也可以指定 socket.LWIP_GP(4G)、socket.LWIP_STA(WiFi STA)、socket.LWIP_ETH(以太网)等 |
| host | string | 是 | FTP 服务器地址,可以是域名也可以是 IP。传空会直接打印 host不能为空 并返回 nil |
| port | number | 否 | 服务器端口,默认 21 |
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| ftpc | table/nil | 成功返回客户端实例(后续方法都用 ftpc:方法名() 调用);失败返回 nil |
示例
-- 使用默认网卡连接
local ftpc = exftp.create(nil, "121.43.224.154", 21)
-- 指定走 4G 网卡
local ftpc = exftp.create(socket.LWIP_GP, "ftp.example.com", 21)
if not ftpc then
log.error("ftp", "连接失败")
end
注意事项
- 本函数内部会
sys.waitUntil()等事件,必须在 task 里调用(sys.taskInit或其它协程),不能在顶层直接调用。 - 内部有两段各 5 秒的等待:先等 TCP 连接建立,再等服务器的
220响应。因此最坏情况下会阻塞 10 秒才返回nil;服务器很慢时不要以为程序卡死了。 - 返回
nil的常见原因:网卡还没拿到 IP、host/port 写错、服务器防火墙不放行、服务器不返回220。创建失败时库内部已经socket.close+socket.release,不需要你再释放。 - 成功返回的实例一定要在不用时调
close(),否则命令通道的 socket 会一直占着。
4.2 exftp:auth(username, password)
功能
登录 FTP 服务器,内部依次发送 USER 和 PASS 两条命令。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | string | 是 | 登录用户名 |
| password | string | 是 | 登录密码 |
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 登录成功;false 登录失败或当前状态不是"已连接未认证" |
示例
local ftpc = exftp.create(nil, "121.43.224.154", 21)
if ftpc and ftpc:auth("ftp_user", "3QujbiMG") then
log.info("ftp", "登录成功")
else
log.error("ftp", "登录失败")
end
注意事项
- 只允许在
create()之后调用一次。已经登录成功后再调auth()会返回false(状态不匹配)。 - 服务器允许匿名登录时,
USER直接回230,库会跳过PASS并返回true。 - 每条命令等 5 秒响应,登录最坏情况会阻塞 10 秒。
4.3 exftp:upload(local_path, remote_path, opts)
功能
把本地文件上传到服务器,等价于 FTP 的 STOR 命令,采用被动模式 + 分块发送。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| local_path | string | 是 | 本地文件路径,如 /test_upload.txt,相对于设备文件系统根目录 |
| remote_path | string | 是 | 远端文件路径,如 /upload/test.txt。相对路径会落到服务器当前工作目录下 |
| opts | table | 是 | 选项表,见下表。必须显式传入,至少包含 timeout |
| opts.timeout | number | 否 | 上传总超时,单位毫秒,默认 5 * 60 * 1000(5 分钟) |
| opts.buffer_size | number | 否 | 分块缓冲区大小,单位字节。不填默认 128 KB,内存不足时依次降级到 64 KB、24 KB、8 KB |
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 上传成功;false 上传失败 |
示例
-- 指定 60 秒超时,缓冲区用默认的 128 KB
local ok = ftpc:upload("/test_upload.txt", "/test_upload.txt", { timeout = 60 * 1000 })
log.info("ftp", "上传", ok)
-- 内存紧张时可以手动把缓冲区调到 16 KB
local ok = ftpc:upload("/big.bin", "/big.bin", { timeout = 10 * 60 * 1000, buffer_size = 16 * 1024 })
注意事项
opts不要省略。当前版本进入传输流程时会读取opts.timeout做超时判断,省略opts会导致该值缺失、函数调用报错。写法统一成{ timeout = 毫秒数 }最稳妥。- 本地文件不存在、或者文件大小为 0,函数直接返回
false,连命令都不会发。 - 判断成功的条件是"发送字节数等于文件大小"或"收到 226 响应",两者满足其一即返回
true。中途超时会返回false,此时服务器上可能残留一个不完整的文件。 - 上传期间不能并发调用本实例的其它方法,因为命令通道被占用;需要同时传多个文件就开多个实例。
- 打印进度:先调
ftpc:debug(true),库会每 1 MB 输出一条"已上传 x/y (百分比)"的日志。
4.4 exftp:download(remote_path, local_path, opts)
功能
把服务器上的文件下载到本地,等价于 RETR 命令。下载前会先发 SIZE 取远端文件大小,用于判断何时接收完成。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| remote_path | string | 是 | 远端文件路径,如 /download/test.txt |
| local_path | string | 是 | 本地保存路径,如 /downloaded.txt。文件已存在会被覆盖 |
| opts | table | 否 | 选项表 |
| opts.timeout | number | 否 | 下载总超时,单位毫秒,默认 5 * 60 * 1000(5 分钟) |
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 流程完成;false 远端文件取大小失败、数据通道建立失败、本地文件创建失败等 |
示例
local ok = ftpc:download("/test_upload.txt", "/downloaded.txt", { timeout = 30 * 1000 })
if ok then
log.info("ftp", "下载完成", "大小", io.fileSize("/downloaded.txt"))
else
log.error("ftp", "下载失败")
end
注意事项
- 参数顺序和
upload相反:download是"远端在前、本地在后",而upload是"本地在前、远端在后",写反了会变成一个不存在的文件名,表现为返回false。 - 服务器必须支持
SIZE命令。本库在RETR之前一定先发SIZE,拿不到213响应就直接返回false。部分精简 FTP 服务器(或把SIZE关掉的服务器)不支持,遇到"能上传、不能下载"就是这里。 - 返回
true不等于文件完整。当前版本在传输超时(timeout到期)时也会走到return true,只是文件内容不全。因此大文件下载完建议用io.fileSize()和预期大小比一下。 - 下载是流式写入,不会把整个文件读进内存,几 MB 的文件也不会爆内存。
- 目录不存在不会自动创建,
local_path的父目录必须已存在。 - 同样支持
debug(true)打印进度,默认每 100 KB 输出一条。
4.5 exftp:chdir(path)
功能
切换服务器上的当前工作目录,等价于 CWD 命令。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | 目标目录,绝对路径(/upload)和相对路径(../data)都可以 |
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 切换成功(服务器回 250);false 目录不存在、无权限或状态不对 |
示例
if ftpc:chdir("/upload") then
log.info("ftp", "已切到 /upload")
-- 之后的 upload/download 用相对路径就会落在这个目录下
ftpc:upload("/test_upload.txt", "test_upload.txt", { timeout = 60 * 1000 })
end
注意事项
- 目录不存在时不会自动创建(本库没有
MKD),调用前请确认服务器上已经有这个目录。 - 切换失败不会改变当前目录,后续操作仍在原目录下进行。
4.6 exftp:pwd()
功能
查询服务器当前工作目录,等价于 PWD 命令。
参数
无。
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 查询成功;false 失败 |
| path | string/nil | 成功时返回目录路径,如 /upload;失败返回 nil |
示例
local ok, dir = ftpc:pwd()
if ok then
log.info("ftp", "当前目录", dir)
end
注意事项
- 本函数返回两个值,第一个是成功标志,第二个才是路径,别只接第一个。
- 服务器响应格式不规范(
257后面的路径没有加引号)时,库会退化为按空白切分取第一段,个别服务器可能解析出不完整的路径。
4.7 exftp:cdup()
功能
返回上一级目录,等价于 CDUP 命令。
参数
无。
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| result | boolean | true 成功;false 失败(已经在根目录时多数服务器也返回失败) |
示例
if ftpc:cdup() then
log.info("ftp", "已返回上级目录")
end
注意事项
- 已经在根目录
/时,服务器通常回550,此时函数返回false,属于正常现象,不用当错误处理。
4.8 exftp:debug(onoff)
功能
打开或关闭本实例的调试日志,同时把底层 socket 的调试开关一起设置。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| onoff | boolean | 是 | true 打开,false(或不传)关闭 |
返回值
无。
示例
ftpc:debug(true) -- 打开后能看到 PASV 得到的 IP/端口、传输进度、当前目录等
-- ... 调试完再关掉,避免日志刷屏
ftpc:debug(false)
注意事项
- 打开后会额外输出 FTP 命令交互细节和传输进度,正式产品里请关掉,否则大文件传输时日志量很大。
- 这个开关只影响日志,不影响功能。
4.9 exftp:close()
功能
关闭连接并释放资源:先关数据通道,再关命令通道 socket,最后把状态置为"未连接"。
参数
无。
返回值
无。
示例
ftpc:close()
ftpc = nil
注意事项
- 重复调用
close()是安全的,不会报错。 - 调用后再执行
auth/upload/download/chdir/pwd/cdup一律返回false,因为状态已经回到"未连接"。 - 关闭后如果想继续用,必须重新
create()。
4.10 exftp.version()
功能
返回 exftp 库文件的版本号,格式为 yyyymmddhhmm,方便排查"设备上跑的是哪个版本的库"。
参数
无。
返回值
| 返回值 | 类型 | 说明 |
|---|---|---|
| version | string | 12 位版本号字符串,例如 "202607021200",表示 2026 年 7 月 2 日 12:00 发布的版本 |
示例
log.info("exftp", "库版本", exftp.version())
-- 输出类似:I/user.exftp 库版本 202607021200
注意事项
- 这是库文件的版本号,跟固件版本号无关,也与
rtos.version()无关。 - 注意它是点号调用
exftp.version(),不是冒号调用;写成ftpc:version()也能跑,但不推荐。
五、版本更新说明
版本号:202607021200
1、更新时间:2026-07-02 12:00
2、更新内容
- 新增
exftp.version()接口 - 支持 exftp 库文件版本号管理功能,版本号格式为
yyyymmddhhmm,表示 yyyy 年 mm 月 dd 日 hh 时 mm 分发布的版本
六、产品支持说明
exftp 是纯 Lua 脚本库,不占用固件空间、不需要在 BSP 里打开任何宏,只要固件具备 socket、io、zbuff 三个核心库并且能联网,就可以使用。因此:
- 4G 模组:Air780E 系列(Air780EPM / Air780EHM / Air780EHV / Air780EGH / Air780EGG / Air780EGP 等)、Air8000 系列都可以直接使用,走
socket.LWIP_GP网卡。 - WiFi 模组:Air8101 系列走
socket.LWIP_STA网卡;Air8000 系列同时具备 4G 和 WiFi,可以按需选择。 - 官方自动化用例实际覆盖了 Air8000、Air780EPM、Air780EHM、Air780EHV、Air780EGH、Air780EGG、Air780EGP 和 Air8101,并验证了"向不支持的网卡连接时应正确报错"这一行为。
需要注意的是:库文件要自己放进项目(script/libs/exftp.lua 不会被编进固件),换固件、换模组都不用改代码,把库文件跟着项目走即可。
七、常见问题与解决方案
7.1 require "exftp" 报找不到模块
问题描述:运行时报 module 'exftp' not found,或 attempt to index a nil value。
原因:exftp 是脚本库,不是固件内置库,项目里没有这个文件。
解决:从 LuatOS 仓库 script/libs/exftp.lua 复制到你项目的 libs/ 目录(或 main.lua 同级目录),再 require "exftp"。用 Luatools 新建工程时如果选了带 libs 的模板,注意确认里面有 exftp.lua。
7.2 create() 一直返回 nil
问题描述:exftp.create(nil, host, port) 返回 nil,日志里能看到"创建命令通道socket失败"或"等待服务就绪响应超时"。
原因与解决:
- 网卡还没有 IP——这是最常见的原因。调用
create()之前先while not socket.adapter(socket.dft()) do sys.waitUntil("IP_READY", 1000) end。 - 主机或端口写错,或者服务器只开放了 FTPS(990 端口),本库不支持 TLS,连上去也拿不到
220。 - 服务器连接后不发
220:少数服务器要等客户端先发命令,本库要求先收到220才认为就绪。 - 想确认是网络问题还是服务器问题,先用
socket.tcp连一下 21 端口试试。
7.3 upload() 返回 false
问题描述:登录成功、pwd() 也正常,但上传一直失败。
原因与解决:
- 本地文件不存在或大小为 0——库在读文件、取大小这两步就会返回
false,不会发任何命令。先用io.exists()和io.fileSize()确认。 opts没传:本版本必须显式传{ timeout = 毫秒 },否则调用会直接异常。- 服务器目录不存在或无写权限:
STOR会回550,库判断响应码无效后返回false。先用chdir()确认能进到目标目录。 - 超时太短:默认 5 分钟,但弱网下传几 MB 可能不够,可以按
文件大小 / 实测速率再放宽一倍。 - 打开
debug(true)看日志里STOR的响应码,550是权限/路径问题,425是数据通道没建起来。
7.4 download() 返回 false,日志里是"获取远程文件大小失败"
问题描述:上传正常,下载一律失败,日志出现 获取远程文件大小失败。
原因:本库在 RETR 之前必须先用 SIZE 拿到远端文件大小,服务器不支持 SIZE(或返回 550)就无法继续。
解决:
- 换一个支持
SIZE的服务器(vsftpd、FileZilla Server、大部分云 FTP 都支持)。 - 确认文件路径正确、当前用户对该文件有读权限——文件不存在时
SIZE也回550,表现和"不支持 SIZE"一样,先chdir()+pwd()确认路径。
7.5 download() 返回 true,但文件不完整
问题描述:函数返回 true,本地文件却比服务器上的小,或者内容是截断的。
原因:当前版本在下载超时(opts.timeout 到期)时仍会走到 return true,只把失败写进了日志(下载超时)。
解决:下载完用 io.fileSize(local_path) 和已知的远端大小比对;对完整性有要求时,可以在文件尾部带校验值,或者改用 httpplus 走 HTTP 下载。
7.6 PASV 返回的地址连不上(服务器在 NAT 后面)
问题描述:PASV 成功,但建立数据通道失败,upload / download 返回 false。
原因:部分 FTP 服务器部署在 NAT/容器里,227 响应里回的是内网地址(192.168.x.x、10.x.x.x、172.16~31.x.x),设备在公网上当然连不到。
解决:在服务器端配置被动模式的外部地址(vsftpd 的 pasv_address、FileZilla Server 的"被动模式外部 IP"),让它返回公网 IP;这类问题只能从服务器侧改,客户端侧本库没有提供覆盖地址的接口。
7.7 传输速度慢
原因与优化方向:
- 缓冲区大小:默认 128 KB 已经比较合适,内存紧张时库会自动降到 64/24/8 KB,速度会明显变慢——可以手动传
buffer_size指定一个能分配成功的值。 - 弱网(信号差、丢包重传多)是主要瓶颈,4G 模组可以先看
mobile.csq()确认信号强度(CSQ 并不能完全代表实际速率,只作参考)。 debug(true)打开时会额外打大量日志,测速时记得关掉。