跳转至

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失败"或"等待服务就绪响应超时"。

原因与解决:

  1. 网卡还没有 IP——这是最常见的原因。调用 create() 之前先 while not socket.adapter(socket.dft()) do sys.waitUntil("IP_READY", 1000) end。
  2. 主机或端口写错,或者服务器只开放了 FTPS(990 端口),本库不支持 TLS,连上去也拿不到 220。
  3. 服务器连接后不发 220:少数服务器要等客户端先发命令,本库要求先收到 220 才认为就绪。
  4. 想确认是网络问题还是服务器问题,先用 socket.tcp 连一下 21 端口试试。

7.3 upload() 返回 false

问题描述:登录成功、pwd() 也正常,但上传一直失败。

原因与解决:

  1. 本地文件不存在或大小为 0——库在读文件、取大小这两步就会返回 false,不会发任何命令。先用 io.exists() 和 io.fileSize() 确认。
  2. opts 没传:本版本必须显式传 { timeout = 毫秒 },否则调用会直接异常。
  3. 服务器目录不存在或无写权限:STOR 会回 550,库判断响应码无效后返回 false。先用 chdir() 确认能进到目标目录。
  4. 超时太短:默认 5 分钟,但弱网下传几 MB 可能不够,可以按 文件大小 / 实测速率 再放宽一倍。
  5. 打开 debug(true) 看日志里 STOR 的响应码,550 是权限/路径问题,425 是数据通道没建起来。

7.4 download() 返回 false,日志里是"获取远程文件大小失败"

问题描述:上传正常,下载一律失败,日志出现 获取远程文件大小失败。

原因:本库在 RETR 之前必须先用 SIZE 拿到远端文件大小,服务器不支持 SIZE(或返回 550)就无法继续。

解决:

  1. 换一个支持 SIZE 的服务器(vsftpd、FileZilla Server、大部分云 FTP 都支持)。
  2. 确认文件路径正确、当前用户对该文件有读权限——文件不存在时 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 传输速度慢

原因与优化方向:

  1. 缓冲区大小:默认 128 KB 已经比较合适,内存紧张时库会自动降到 64/24/8 KB,速度会明显变慢——可以手动传 buffer_size 指定一个能分配成功的值。
  2. 弱网(信号差、丢包重传多)是主要瓶颈,4G 模组可以先看 mobile.csq() 确认信号强度(CSQ 并不能完全代表实际速率,只作参考)。
  3. debug(true) 打开时会额外打大量日志,测速时记得关掉。
搜索