# 监听目录变化
<subtitle>监听沙箱目录中的文件系统变化事件。</subtitle>

您可以使用 `files.watch_dir()` 方法监听目录的变化。

> 由于事件是异步跟踪的，其传递可能会延迟。建议不要在进行更改后立即收集或关闭监听器。

```python
from ucloud_sandbox import Sandbox, FilesystemEventType

sandbox = Sandbox.create()
dirname = '/home/user'

# 监听目录变化
handle = sandbox.files.watch_dir(dirname)
# 触发文件写入事件
sandbox.files.write(f"{dirname}/my-file", "hello")

# 检索自上次 `get_new_events()` 调用以来的最新事件
events = handle.get_new_events()
for event in events:
  print(event)
  if event.type == FilesystemEventType.WRITE:
    print(f"wrote to file {event.name}")
```

## 递归监听

您可以使用 `recursive` 参数启用递归监听。

> 快速创建新文件夹时（例如，深度嵌套的文件夹路径），除了 `CREATE` 之外的事件可能不会被触发。为避免这种行为，请提前创建所需的文件夹结构。

```python
from ucloud_sandbox import Sandbox, FilesystemEventType

sandbox = Sandbox.create()
dirname = '/home/user'

# 监听目录变化
handle = sandbox.files.watch_dir(dirname, recursive=True)
# 触发文件写入事件
sandbox.files.write(f"{dirname}/my-folder/my-file", "hello")

# 检索自上次 `get_new_events()` 调用以来的最新事件
events = handle.get_new_events()
for event in events:
  print(event)
  if event.type == FilesystemEventType.WRITE:
    print(f"wrote to file {event.name}")
```

## 包含条目信息

您可以使用 `include_entry` 参数在每个事件中包含受影响文件或目录的信息。启用后，每个事件都会在 `entry` 字段中携带条目的信息——例如其路径、类型和大小。

> 对于删除事件，条目信息可能未设置，因为路径已不存在。包含条目信息需要 envd 版本 `v0.6.3` 或更高版本的模板——在旧沙箱上使用 `include_entry` 选项将抛出错误。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
dirname = '/home/user'

# 监听目录变化
handle = sandbox.files.watch_dir(dirname, include_entry=True)
# 触发文件写入事件
sandbox.files.write(f"{dirname}/my-file", "hello")

# 检索自上次 `get_new_events()` 调用以来的最新事件
events = handle.get_new_events()
for event in events:
  print(event.type, event.name, event.entry.path if event.entry else None)
```

## 监听网络文件系统挂载

默认情况下，监听网络文件系统挂载（NFS、CIFS、SMB、FUSE）上的路径会被拒绝。您可以使用 `allow_network_mounts` 参数显式选择启用。

> 网络挂载上的事件可能不可靠或根本不会传递，这就是需要显式选择启用的原因。
> 
> 从沙箱外的另一个客户端进行的更改（例如，另一台机器写入同一网络共享）**不会**传播到监听器——只有从沙箱内进行的更改才会被检测到。

> 监听网络挂载需要 envd 版本 `v0.6.4` 或更高版本的模板——在旧沙箱上使用 `allow_network_mounts` 选项将抛出错误。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
dirname = '/mnt/nfs-share/my-dir'

# 监听网络挂载上的目录变化
handle = sandbox.files.watch_dir(dirname, allow_network_mounts=True)
# 触发文件写入事件
sandbox.files.write(f"{dirname}/my-file", "hello")

# 检索自上次 `get_new_events()` 调用以来的最新事件
events = handle.get_new_events()
for event in events:
  print(event.type, event.name)
```