Lua 文件 I/O（实战总结）

Lua 文件 I/O 简介：从零开始掌握文件读写

在编程世界里，数据的存储与读取是程序运行的“生命线”。无论是保存用户配置、记录日志，还是处理大量文本信息，文件 I/O 都扮演着至关重要的角色。Lua 作为一门轻量级、嵌入式脚本语言，虽然体积小，但其内置的文件操作能力却非常实用，尤其适合游戏开发、嵌入式系统和配置管理场景。

今天我们就来深入聊聊 Lua 文件 I/O，带你从基础语法到实用技巧，一步步掌握如何在 Lua 中读写文件。无论你是初学者，还是已有一定经验的开发者，这篇文章都会让你对 Lua 的文件操作有更清晰的理解。

打开与关闭文件：文件 I/O 的起点

在 Lua 中，操作文件的第一步是打开文件。Lua 提供了一个标准库 io，它包含了所有与文件相关的函数。我们使用 io.open() 函数来打开一个文件，该函数返回一个文件句柄（file handle），后续的所有读写操作都通过这个句柄进行。

-- 打开一个文件，模式为只读（"r"）
local file = io.open("example.txt", "r")

-- 检查文件是否成功打开
if file then
    print("文件打开成功")
else
    print("文件打开失败，请检查路径或文件是否存在")
end

-- 关闭文件（非常重要！）
io.close(file)

💡 提示：文件句柄就像是你进入图书馆的“入场券”。你必须先拿到它，才能借书（读取数据）或还书（写入数据）。如果不关闭，就像忘记还书，可能导致资源浪费或程序异常。

文件打开的模式决定了你对文件的操作权限，常见的模式有：

• "r"：只读模式，用于读取文件内容
• "w"：写入模式，会清空原文件内容
• "a"：追加模式，将内容写入文件末尾，不覆盖原有内容
• "r+"：读写模式，可读可写，文件必须存在
• "w+"：读写模式，会清空文件内容

读取文件内容：从文件中“取数据”

读取文件是文件 I/O 的常见需求。Lua 提供了多种读取方式，根据你的需要选择最合适的方法。

逐行读取：适合处理日志或配置文件

如果你的文件是一行一行的文本（比如日志文件），推荐使用 file:read("*line")。

-- 打开文件，以只读模式
local file = io.open("log.txt", "r")

-- 判断文件是否打开成功
if not file then
    print("无法打开文件 log.txt")
    return
end

-- 逐行读取内容
while true do
    local line = file:read("*line")
    if line == nil then break end  -- 读到文件末尾时，read 返回 nil
    print("读取到一行：", line)
end

-- 关闭文件
io.close(file)

📌 比喻：这就像你在翻一本日记，一页一页地看，直到看完为止。*line 就是“下一页”的指令。

一次性读取全部内容：适合小文件处理

如果文件不大（比如小于 100KB），可以一次性读取全部内容。

local file = io.open("config.txt", "r")

if not file then
    print("配置文件不存在")
    return
end

-- 一次性读取整个文件内容
local content = file:read("*all")

print("文件内容如下：")
print(content)

io.close(file)

✅ 优点：代码简洁，适合快速处理小文件
⚠️ 注意：大文件使用 *all 可能导致内存占用过高，不推荐

按字符或字节数读取：精准控制读取粒度

如果你需要精确控制读取多少字符，可以使用 file:read(n)，其中 n 是要读取的字符数。

local file = io.open("data.bin", "r")

if not file then
    print("文件打开失败")
    return
end

-- 一次读取 5 个字符
local chunk = file:read(5)
print("读取了 5 个字符：", chunk)

-- 继续读取下 5 个
chunk = file:read(5)
print("再读取 5 个字符：", chunk)

io.close(file)

写入文件：将数据“存入”文件

写入文件是数据持久化的关键。Lua 的写入操作非常直观，只需要调用 file:write() 函数即可。

覆盖写入：清空原有内容

使用 "w" 模式打开文件，会清空原文件内容，然后写入新数据。

-- 打开文件，以写入模式（覆盖）
local file = io.open("output.txt", "w")

if not file then
    print("无法创建输出文件")
    return
end

-- 写入三行文本
file:write("第一行：Hello Lua!\n")
file:write("第二行：欢迎学习文件 I/O\n")
file:write("第三行：你已经掌握基础了\n")

-- 关闭文件，确保数据写入磁盘
io.close(file)

print("文件写入完成")

✅ 推荐：在写入完成后务必调用 io.close()，否则数据可能未真正写入磁盘。

追加写入：保留原有内容

如果你不想覆盖原文件，而是希望在末尾添加内容，使用 "a" 模式。

local file = io.open("log.txt", "a")

if not file then
    print("无法打开日志文件")
    return
end

-- 追加一条时间戳日志
file:write(os.date("%Y-%m-%d %H:%M:%S"), " - 程序运行成功\n")

io.close(file)

📌 小技巧：os.date() 是 Lua 内置函数，可获取当前时间，常用于日志记录。

文件操作的高级技巧：路径、错误处理与最佳实践

处理文件路径：跨平台兼容性

在不同操作系统中，路径分隔符不同（Windows 用 \，Linux/macOS 用 /）。Lua 提供了 io.path 模块（在某些 Lua 实现中可用）或手动拼接路径。

-- 推荐使用路径连接函数（如使用 penlight 库）
-- 但若无外部库，可用字符串拼接
local path = "data" .. "/" .. "config.lua"

-- 也可以使用 os.getenv 获取环境变量
local home = os.getenv("HOME")  -- Linux/macOS
-- local home = os.getenv("USERPROFILE")  -- Windows

local full_path = home .. "/projects/config.lua"

💡 提示：尽量使用 / 作为路径分隔符，即使在 Windows 上也通用。

错误处理：让程序更健壮

文件操作容易出错，比如文件不存在、权限不足等。合理使用 if not file 判断可以避免程序崩溃。

local function safe_read_file(filename)
    local file = io.open(filename, "r")
    if not file then
        print("错误：无法打开文件", filename)
        return nil
    end

    local content = file:read("*all")
    io.close(file)

    return content
end

-- 使用示例
local data = safe_read_file("config.txt")
if data then
    print("读取成功：", data)
else
    print("读取失败")
end

实际案例：配置文件读取器

我们来做一个实用的小工具：一个读取 .cfg 配置文件的脚本。

假设 config.cfg 内容如下：

app_name = "MyApp"
version = "1.0.0"
debug = true
max_connections = 100

-- 读取配置文件并解析键值对
function load_config(filename)
    local config = {}
    local file = io.open(filename, "r")

    if not file then
        print("配置文件不存在或无法读取：", filename)
        return config
    end

    for line in file:lines() do
        -- 去除首尾空格
        line = line:match("^%s*(.-)%s*$")

        -- 跳过空行和注释（以 -- 开头）
        if line == "" or line:match("^%s*--") then
            continue
        end

        -- 使用模式匹配提取 key 和 value
        local key, value = line:match("^(%w+)%s*=%s*(.+)$")

        if key and value then
            -- 自动转换类型：字符串、布尔值、数字
            if value == "true" then
                config[key] = true
            elseif value == "false" then
                config[key] = false
            elseif tonumber(value) then
                config[key] = tonumber(value)
            else
                config[key] = value
            end
        end
    end

    io.close(file)
    return config
end

-- 使用
local cfg = load_config("config.cfg")

-- 输出配置
for k, v in pairs(cfg) do
    print(k, ":", v)
end

✅ 输出示例：

app_name : MyApp
version : 1.0.0
debug : true
max_connections : 100

总结：Lua 文件 I/O 的核心要点

通过本文的学习，你已经掌握了 Lua 文件 I/O 的核心技能：

• 如何安全地打开、读取、写入和关闭文件
• 不同读取模式（*line, *all, 数字）的适用场景
• 写入模式的选择：覆盖 vs 追加
• 实际应用中的路径处理、错误判断和配置解析技巧

Lua 文件 I/O 虽然语法简洁，但功能强大，是构建可持久化、可配置程序的重要工具。无论你是开发游戏、工具脚本，还是做自动化处理，掌握它都至关重要。

最后提醒一句：每次打开文件后，务必调用 io.close()。这是保证数据安全、避免资源泄漏的黄金法则。

希望这篇文章能成为你学习 Lua 文件 I/O 的起点。下次当你需要保存数据、读取配置时，记得回来翻翻这篇指南。