Go 语言文件监听fsnotify 实战：热加载配置文件

在开发 Go 应用时，我们经常会遇到这样的需求：当配置文件发生变化时自动重载、当上传目录有新文件时自动处理、或者实现类似 nodemon 的热重启工具。

实现这些功能最 naive 的方法是轮询（Polling）：每隔几秒检查一次文件修改时间。但这不仅浪费 CPU，还有延迟。

fsnotify 是一个跨平台的 Go 语言文件通知库，它利用操作系统底层的 API（如 Linux 的 inotify、macOS 的 kqueue、Windows 的 ReadDirectoryChangesW）来监听文件系统事件，高效且实时。

本文将介绍 fsnotify 的核心用法，并提供两个简单实用的实战例子。

1. 快速开始

安装

go get github.com/fsnotify/fsnotify

核心概念

使用 fsnotify 主要涉及以下几个步骤：

1. 创建 Watcher：初始化监听器。
2. 添加监听路径：指定要监听的文件或目录。
3. 监听事件：通过 channel 接收 Event（事件）和 Error（错误）。
4. 清理资源：程序退出前关闭 Watcher。

2. 基础示例：监听目录变化

这是一个最简化的 Demo，用于理解基本流程。它会监听当前目录，并在终端打印出所有的文件操作。

package main

import (
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/fsnotify/fsnotify"
)

func main() {
	// 1. 创建一个新的 Watcher
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatal("NewWatcher 失败:", err)
	}
	// 记得最后关闭
	defer watcher.Close()

	// 2. 启动一个 goroutine 来处理事件
	go func() {
		for {
			select {
			case event, ok := <-watcher.Events:
				if !ok {
					return
				}
				// 打印事件：操作类型 (Op) 和 文件路径 (Name)
				log.Printf("文件事件: %s %s", event.Op, event.Name)
				
			case err, ok := <-watcher.Errors:
				if !ok {
					return
				}
				log.Println("监听错误:", err)
			}
		}
	}()

	// 3. 添加要监听的路径 (这里监听当前目录 ".")
	// 注意：fsnotify 通常建议监听目录而不是单个文件，兼容性更好
	err = watcher.Add(".")
	if err != nil {
		log.Fatal("Add 路径失败:", err)
	}

	log.Println("开始监听当前目录文件变化... (按 Ctrl+C 退出)")

	// 4. 阻塞主进程，等待信号退出
	sigChan := make(chan os.Signal, 1)
	signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
	<-sigChan
}

运行测试：

1. 运行程序 go run main.go。
2. 在同一个目录下新建一个文件 touch test.txt。
3. 修改文件 echo "hello" >> test.txt。
4. 观察终端输出。

3. 实战场景一：配置文件热重载

这是 fsnotify 最常见的用途。当 config.json 改变时，无需重启服务，自动加载新配置。

关键点

• 编辑器行为：很多编辑器（如 VSCode, Vim）保存文件时，实际上是删除旧文件并创建新文件，而不是直接写入。因此不能只监听 Write 事件，还要监听 Create 和 Remove。
• 监听目录：为了兼容上述编辑器行为，建议监听配置文件所在的目录。

代码示例

package main

import (
	"encoding/json"
	"log"
	"os"
	"sync"
	"time"

	"github.com/fsnotify/fsnotify"
)

// 模拟全局配置
type Config struct {
	AppName string `json:"app_name"`
	Port    int    `json:"port"`
}

var (
	currentConfig Config
	configMutex   sync.RWMutex
	configPath    = "./config.json"
)

// 加载配置函数的模拟
func loadConfig() error {
	file, err := os.ReadFile(configPath)
	if err != nil {
		return err
	}
	var cfg Config
	if err := json.Unmarshal(file, &cfg); err != nil {
		return err
	}
	
	configMutex.Lock()
	currentConfig = cfg
	configMutex.Unlock()
	
	log.Printf("配置已重载：AppName=%s, Port=%d", cfg.AppName, cfg.Port)
	return nil
}

func main() {
	// 初始化一个默认配置
	currentConfig = Config{AppName: "Default", Port: 8080}

	// 创建 Watcher
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatal(err)
	}
	defer watcher.Close()

	// 监听配置所在的目录，而不是文件本身
	// 假设 config.json 在当前目录
	err = watcher.Add(".")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("服务启动，监听配置变化...")

	// 防抖计时器 (Debouncing)
	// 防止保存文件时触发多次事件
	var timer *time.Timer

	for {
		select {
		case event, ok := <-watcher.Events:
			if !ok {
				return
			}
			
			// 只关心 config.json 的变化
			if event.Name != configPath {
				continue
			}

			// 简单的防抖逻辑：如果 500ms 内没有新事件，才执行加载
			if timer != nil {
				timer.Stop()
			}
			timer = time.AfterFunc(500*time.Millisecond, func() {
				// 检查文件是否存在，防止 Remove 事件导致加载失败
				if _, err := os.Stat(configPath); err == nil {
					if err := loadConfig(); err != nil {
						log.Println("重载配置失败:", err)
					}
				}
			})

		case err, ok := <-watcher.Errors:
			if !ok {
				return
			}
			log.Println("监听错误:", err)
		}
	}
}

测试方法：

1. 创建一个 config.json: {"app_name": "v1", "port": 8080}。
2. 运行程序。
3. 修改 json 为 {"app_name": "v2", "port": 9090} 并保存。
4. 观察日志，会发现配置自动更新了。

4. 实战场景二：文件同步/备份触发

假设有一个上传目录 uploads/，一旦有新文件放入，我们需要自动将其备份到 backup/ 目录。

代码示例

package main

import (
	"io"
	"log"
	"os"
	"path/filepath"

	"github.com/fsnotify/fsnotify"
)

const (
	watchDir = "./uploads"
	backupDir = "./backup"
)

func main() {
	// 确保备份目录存在
	os.MkdirAll(backupDir, 0755)
	// 确保监听目录存在
	os.MkdirAll(watchDir, 0755)

	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatal(err)
	}
	defer watcher.Close()

	err = watcher.Add(watchDir)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("开始监听 %s 目录的新文件...", watchDir)

	for {
		select {
		case event, ok := <-watcher.Events:
			if !ok {
				return
			}
			
			// 只处理创建和写入事件
			if event.Op&fsnotify.Create == fsnotify.Create || 
			   event.Op&fsnotify.Write == fsnotify.Write {
				
				// 排除目录本身的事件，只处理文件
				info, err := os.Stat(event.Name)
				if err != nil || info.IsDir() {
					continue
				}

				log.Println("检测到新/修改文件:", event.Name)
				go backupFile(event.Name)
			}

		case err, ok := <-watcher.Errors:
			if !ok {
				return
			}
			log.Println("错误:", err)
		}
	}
}

// 简单的备份函数
func backupFile(srcPath string) {
	// 获取文件名
	fileName := filepath.Base(srcPath)
	dstPath := filepath.Join(backupDir, fileName)

	srcFile, err := os.Open(srcPath)
	if err != nil {
		log.Printf("打开源文件失败 %s: %v", srcPath, err)
		return
	}
	defer srcFile.Close()

	dstFile, err := os.Create(dstPath)
	if err != nil {
		log.Printf("创建目标文件失败 %s: %v", dstPath, err)
		return
	}
	defer dstFile.Close()

	_, err = io.Copy(dstFile, srcFile)
	if err != nil {
		log.Printf("复制文件失败: %v", err)
		return
	}
	log.Printf("备份成功：%s -> %s", srcPath, dstPath)
}

5. 避坑指南与最佳实践

在使用 fsnotify 时，以下几个坑需要注意：

1. 跨平台差异：

   • Linux: 基于 inotify，性能很好。
   • macOS: 基于 FSEvents/kqueue。
   • Windows: 基于 ReadDirectoryChangesW。
   • 注意：不同系统对事件的触发时机和类型可能略有不同，务必在多平台测试。

2. 编辑器保存机制：

   • 如前所述，Vim/VSCode/GoLand 等编辑器保存文件时，往往不是直接 Write，而是 Write -> Close -> Remove -> Create 或者 Create Temp -> Rename。
   • 解决方案：监听目录而不是文件，并且同时处理 Create, Write, Remove, Chmod 事件。

3. 事件风暴 (Debouncing)：

   • 保存一次文件可能会触发多个连续事件（例如 IDE 的自动格式化、临时文件创建）。
   • 解决方案：使用计时器（如上面配置重载例子中的 time.AfterFunc），在事件停止触发一段时间后再执行逻辑。

4. 资源泄露：

   • fsnotify.Watcher 持有操作系统资源。
   • 解决方案：务必使用 defer watcher.Close()，并在程序退出时确保执行。

5. 递归监听：

   • fsnotify 不支持 递归监听子目录。
   • 解决方案：如果需要监听整个树，需要自己遍历目录，对每个子目录调用 watcher.Add()。当监听到有新目录创建时，记得也要 Add 新目录。

6. 总结

fsnotify 是 Go 生态中处理文件系统事件的标准库。它轻量、高效且跨平台。

• 适用场景：配置热更、文件同步、日志收集、代码热重载工具。
• 核心技巧：监听目录而非文件、做好事件防抖、注意编辑器行为差异。