WezTerm 进程信息 Lua 模块 wezterm.procinfo 完全指南：查询 PID、工作目录与进程树-开发者社区

WezTerm 进程信息 Lua 模块 wezterm.procinfo 完全指南：查询 PID、工作目录与进程树

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm

导读

wezterm.procinfo是 WezTerm 内置的 Lua 模块，用于在配置脚本中查询本地系统上运行进程的相关信息，例如当前进程的 PID、指定进程的可执行文件路径、当前工作目录，以及以指定 PID 为根的完整进程树。借助该模块，你可以在 WezTerm 的 Lua 配置与事件钩子中读取进程元数据，从而实现"按进程环境定制界面/行为"的实战方案。读完本文，你将掌握该模块 4 个函数的全部用法、返回对象字段含义，以及它在 Linux / macOS / Windows 三套平台下的底层实现原理。

模块概览

wezterm.procinfo自版本20220807-113146-c2fee766起可用（见模块主文档）。它是一个只读的进程信息查询接口，不与终端模拟或多路复用逻辑耦合，专注于回答三个问题：

当前进程是谁（PID 是多少）？
某个 PID 对应的程序在哪、在哪个目录下运行？
某个 PID 及其子孙进程构成了怎样的进程树？

该模块共暴露 4 个函数，全部为同步调用、无参数或单参数（PID），并遵循"查不到即返回nil"的约定，不会在脚本中抛错。函数注册入口见 procinfo-funcs 的 Lua 绑定源码。

函数	参数	返回值
`wezterm.procinfo.pid()`	无	当前进程的 PID（整数）
`wezterm.procinfo.current_working_dir_for_pid(pid)`	`pid: u32`	进程当前工作目录字符串，或`nil`
`wezterm.procinfo.executable_path_for_pid(pid)`	`pid: u32`	进程可执行映像的完整路径字符串，或`nil`
`wezterm.procinfo.get_info_for_pid(pid)`	`pid: u32`	进程信息对象`LocalProcessInfo`，或`nil`

四个 API 函数详解

pid()：获取当前进程 PID

> wezterm.procinfo.pid()

返回调用时所在进程的进程标识符。在 Lua 绑定中，它直接封装了 C 库的libc::getpid()（见 procinfo-funcs 注册代码），因此语义与 POSIXgetpid完全一致：得到的是当前正在执行脚本的 WezTerm 进程（通常是wezterm-gui）的 PID。官方文档见 pid()。

该函数通常不单独使用，而是作为另外三个函数的基础参数，例如"查询我自己在哪个目录下工作"：

> wezterm.procinfo.current_working_dir_for_pid(wezterm.procinfo.pid())

current_working_dir_for_pid(pid)：查询进程当前工作目录

> wezterm.procinfo.current_working_dir_for_pid(wezterm.procinfo.pid()) "/home/wez/wez-personal/wezterm"

给定一个 PID，返回该进程的当前工作目录的绝对路径。若无法获取（进程已退出、权限不足或平台不支持），返回nil。官方文档见 current_working_dir_for_pid(pid)。

在绑定层，返回值经过了PathBuf→&str→String的转换，若路径本身无法转为 UTF-8 字符串也会得到nil（见 procinfo-funcs/src/lib.rs）。

executable_path_for_pid(pid)：查询进程可执行文件路径

> wezterm.procinfo.executable_path_for_pid(wezterm.procinfo.pid()) "/home/wez/wez-personal/wezterm/target/debug/wezterm-gui"

给定一个 PID，返回该进程可执行映像（executable image）的完整路径。官方文档见 executable_path_for_pid(pid)。与current_working_dir_for_pid相同，查不到时返回nil。

值得注意的是，"可执行映像路径"与进程的name字段并不总是相同：可执行路径反映的是磁盘上的真实二进制位置，而进程名可能被setproctitle()之类的手段在运行时改写（源码注释对此有明确说明，见 procinfo/src/lib.rs）。

get_info_for_pid(pid)：获取结构化进程信息

> wezterm.procinfo.get_info_for_pid(wezterm.procinfo.pid()) { "argv": [ "/home/wez/wez-personal/wezterm/target/debug/wezterm-gui", ], "children": { 540513: { "argv": [ "-zsh", ], "children": {}, "cwd": "/home/wez", "executable": "/usr/bin/zsh", "name": "zsh", "pid": 540513, "ppid": 540450, "start_time": 232656896, "status": "Sleep", }, }, "cwd": "/home/wez/wez-personal/wezterm", "executable": "/home/wez/wez-personal/wezterm/target/debug/wezterm-gui", "name": "wezterm-gui", "pid": 540450, "ppid": 425276, "start_time": 8671498240, "status": "Run", }

这是 4 个函数中信息最丰富的：它不仅返回目标进程自身的元数据，还会递归构建其全部子孙进程的树形结构（见上面的children嵌套表）。官方文档见 get_info_for_pid(pid)。

LocalProcessInfo：进程信息对象的字段语义

get_info_for_pid返回的对象类型名为LocalProcessInfo，在配置目录中还有一份独立的字段参考文档，其中每个字段都能在 Rust 结构体定义中找到对应实现：

字段	类型	含义
`pid`	整数	进程标识符
`ppid`	整数	父进程标识符
`name`	字符串	进程的 COMM 短名。受平台限制可能被截断（许多系统截断到 15~16 字符）或与实际可执行映像无关，建议优先使用`executable`/`argv`
`executable`	字符串	可执行映像的完整路径（可能为空字符串）
`argv`	表	进程的参数数组。部分系统允许进程在运行时改写 argv 块（如`setproctitle()`）
`cwd`	字符串	进程当前工作目录（不可访问时可能为空路径）
`status`	字符串	进程状态，取值为`Idle`、`Run`、`Sleep`、`Stop`、`Zombie`、`Tracing`、`Dead`、`Wakekill`、`Waking`、`Parked`、`LockBlocked`、`Unknown`
`start_time`	整数	一个以系统相关单位为计数的时钟值，用于指示进程的相对"年龄"（并非所有平台都可移植）
`children`	表	以子进程 PID 为键、值为`LocalProcessInfo`的嵌套表，构成进程树

状态枚举定义于 procinfo/src/lib.rs，其值在 Linux 上直接映射自/proc中的状态字母（见下文）。文档层面，LocalProcessInfo还与 mux-is-process-stateful 事件和 pane:get_foreground_process_info() 相关联，可用于判断会话是否仍然存活。

跨平台底层实现原理

wezterm.procinfo的价值在于屏蔽了三个主流桌面平台截然不同的进程查询机制。Rust crate procinfo 按目标平台编译对应实现，非三大平台的系统（with_root_pid等）一律返回None（见 procinfo/src/lib.rs#L85-L98）。

Linux：直接读取 /proc 伪文件系统

Linux 实现（procinfo/src/linux.rs）完全基于/proc虚拟文件系统：

current_working_dir(pid)：对/proc/{pid}/cwd符号链接执行read_link（见 linux.rs#L23-L25）；
executable_path(pid)：对/proc/{pid}/exe符号链接执行read_link（见 linux.rs#L27-L29）；
with_root_pid(pid)：枚举/proc下所有数字目录得到进程清单，逐进程解析/proc/{pid}/stat提取名称、状态、PPID 与starttime字段，读取/proc/{pid}/cmdline并按\0分割还原 argv，然后按 PPID 关系递归组装成进程树（见 linux.rs#L31-L145）。

Linux 状态字母到LocalProcessStatus的映射也集中在这份文件里：R→Run、S→Sleep、D→Idle、Z→Zombie、T→Stop、t→Tracing、X/x→Dead、K→Wakekill、W→Waking、P→Parked，未知值归入Unknown（见 linux.rs#L4-L20）。

macOS：libc 进程信息 API

macOS 实现（procinfo/src/macos.rs）调用系统 libc 接口：

工作目录通过proc_pidinfo(pid, PROC_PIDVNODEPATHINFO, ...)获取proc_vnodepathinfo结构体，再读取其中的vip_path字节序列并定位\0结尾转为字符串（见 macos.rs#L20-L49）；
可执行路径通过proc_pidpath()获取，缓冲区大小为PROC_PIDPATHINFO_MAXSIZE（见 macos.rs#L51-L60）；
状态枚举由From<u32>转换而来，分别映射Idle、Run、Sleep、Stop、Zombie及Unknown（见 macos.rs#L6-L17）。

Windows：Toolhelp32 快照与 NT 查询接口

Windows 实现（procinfo/src/windows.rs）技术栈最为繁复：

先通过CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, ...)拍摄进程快照并逐条迭代PROCESSENTRY32W（见 windows.rs#L24-L60）；
进程详细信息依赖NtQueryInformationProcess读取 PEB /RTL_USER_PROCESS_PARAMETERS，并通过ReadProcessMemory从目标进程内存中读出参数块；同时兼容 32 位进程（RTL_USER_PROCESS_PARAMETERS32）；
可执行路径使用QueryFullProcessImageNameW，命令行使用CommandLineToArgvW拆分（见 windows.rs#L1-L21）。

实战应用场景

场景一：配置中获取 shell 的真实工作目录

在事件回调（例如根据前台进程环境改变配色或标题）里，你可以组合使用pid()与current_working_dir_for_pid()：

local proc = wezterm.procinfo local me = proc.pid() local cwd = proc.current_working_dir_for_pid(me) if cwd ~= nil then -- 在 wezterm-gui 进程自己的工作目录基础上做判断 end

场景二：遍历进程树、识别子 shell

get_info_for_pid返回的children是嵌套表。以文档示例为例，wezterm-gui（PID 540450）的子树下挂着一个zsh（PID 540513，PPID 540450），通过递归遍历children即可还原"终端 → shell"的父子链路：

local function walk(proc) wezterm.log_info(string.format( "pid=%s name=%s cwd=%s exe=%s", proc.pid, proc.name, proc.cwd, proc.executable )) for _, child in pairs(proc.children or {}) do walk(child) end end local info = wezterm.procinfo.get_info_for_pid(wezterm.procinfo.pid()) if info then walk(info) end

场景三：进程间数据传递（passing-data）

在传递数据的配方文档中，wezterm.procinfo.get_info_for_pid()被推荐为在 WezTerm 各组件（GUI 进程与 mux server 等）之间传递进程信息的标准途径——需要进程详情的一方直接按 PID 向wezterm.procinfo模块查询，从而避免在 IPC 协议里搬运整棵进程树。这种方式天然轻量：调用方只在需要时才真正去操作系统查询，且不同平台由同一套 Lua API 屏蔽差异。

注意事项与限制

版本门槛：整个模块自20220807-113146-c2fee766起才存在，更早的 WezTerm 无法使用，配置中引用前请先做版本判断。
返回nil的三种情形：进程不存在/已退出、权限不足导致内核拒绝查询、路径或参数无法转换为合法 UTF-8 字符串。
字段可靠性：name可能被截断（常见于 15~16 字符限制）或被setproctitle改写；executable与cwd在某些场景下可能为空字符串；start_time的单位是系统相关的，只适合做相对比较，不要跨平台假设其含义。
平台支持：完整的get_info_for_pid仅保证在 Linux、macOS、Windows 上实现；其他目标平台（从 lib.rs 的 cfg 分支看）一律返回nil。
进程树成本：get_info_for_pid需要枚举系统全部进程来组装children树（Linux 上会遍历整个/proc），在调用频率很高的钩子里注意开销，避免每帧调用。