VSCode + Verible LSP：搭建支持跨文件跳转的 Verilog 开发环境

背景

FPGA 工程通常包含数十甚至上百个 Verilog/SystemVerilog 源文件，模块之间层层实例化，信号跨文件互联。如果在 VSCode 中缺少合适的 Language Server，代码阅读和调试会非常低效：想查看某个模块的定义，得手动 grep 文件名；想知道一个模块被哪些地方引用，也得全目录搜索；点击信号名无法跳转到声明处，只能凭记忆翻文件。此外，编辑器还可能对跨文件实例化的模块报 "unknown module" 假错误，干扰真正的语法问题排查。

这篇文章记录如何通过 Verible LSP 为 VSCode 搭建一个支持跨文件跳转定义、查找引用、信号导航的 Verilog 开发环境。

环境搭建

1. 安装语法高亮

安装 eirikpre.systemverilog 扩展，提供 .v / .sv 语法着色。

2. 安装 Verible Language Server

Verible 是 Google/chipsalliance 开源的 SystemVerilog 工具链，其中的 verible-verilog-ls 是一个标准 Language Server，提供跨文件索引、跳转定义、查找引用、诊断等能力。

从 chipsalliance/verible releases 下载 Linux x86_64 静态编译包，解压后将 verible-verilog-ls 放到 ~/.local/bin/ 下。

# 下载
curl -sL "https://github.com/chipsalliance/verible/releases/download/v0.0-4080-ga0a8d8eb/verible-v0.0-4080-ga0a8d8eb-linux-static-x86_64.tar.gz" -o verible.tar.gz

# 提取 LSP
tar -xzf verible.tar.gz
cp verible-*/bin/verible-verilog-ls ~/.local/bin/

3. 安装 Verible VSCode 扩展

在扩展面板搜索并安装 chipsalliance.verible。如果 VSCode 内安装失败，可去 Open VSX 下载 .vsix，手动解压到 ~/.vscode/extensions/chipsalliance.verible/。

4. 项目根目录配置

在项目根目录（Git 仓库顶层）创建 .vscode/settings.json：

{
    "verible.languageServer.path": "/home/huamingh/.local/bin/verible-verilog-ls",

    "[verilog]": {
        "editor.defaultFormatter": "chipsalliance.verible",
        "editor.formatOnSave": false
    },
    "[systemverilog]": {
        "editor.defaultFormatter": "chipsalliance.verible",
        "editor.formatOnSave": false
    }
}

5. 以项目方式打开

关键一步：必须用 VSCode 的 "File → Open Folder" 打开项目根目录，不能只打开单个文件。Verible LSP 会自动索引 workspace 内所有 .v、.sv、.svh 文件，无需手动配置 filelist。

最后 Ctrl+Shift+P → "Reload Window" 使配置生效。

扩展职责对照

扩展	职责
eirikpre.systemverilog	语法高亮
chipsalliance.verible	跨文件 LSP（索引、跳转定义、查找引用、诊断）

实际使用效果

以我的 ip_common 项目为例，package_fifo_v2.v 中实例化了同目录下的 single_clock_simple_dual_port_ram 模块：

single_clock_simple_dual_port_ram #(
    .data_width    (data_width),
    .depth         (2 ** addr_width),
    ...
) u_data_ram (
    .clk      (wclk),
    .wren_a   (ram_wren_a_r),
    ...
);

配置 Verible LSP 后，这块代码的阅读体验有了质的提升：

• Ctrl+Click 跳转定义：按住 Ctrl 点击模块名 single_clock_simple_dual_port_ram，直接跳转到 single_clock_simple_dual_port_ram.v 中的 module single_clock_simple_dual_port_ram #(...) 声明处。点击端口连接中的信号名同样跳转到该信号的 wire / reg 声明。
• Go to References：右键模块名查看所有实例化该模块的位置——对于被几十个文件调用的通用模块来说尤其实用。
• 准确诊断：跨文件实例化的模块不再报 "unknown module" 假错误，红色波浪线只出现在真正有语法问题的地方。

对于动辄几十个模块、跨多层调用的 FPGA 工程，这套环境大幅提升了代码阅读和调试效率。

效果对比

场景	配置前	配置后
查看模块定义	手动 grep 搜索文件名	Ctrl+Click 一键跳转
查找模块被哪些文件引用	grep -r 全目录	右键 Go to References
查看信号定义	凭记忆翻文件	Ctrl+Click 跳转声明
跨文件实例化的模块	红色波浪线 "unknown module"	正确识别，无假错误
语法高亮	无	关键字 / 模块 / 信号着色

总结

• 语法高亮用 eirikpre.systemverilog，跨文件 LSP 用 chipsalliance.verible，两者各司其职
• 必须用 Open Folder 打开项目根目录，LSP 才能跨文件索引
• 每个项目都需要自己的 .vscode/settings.json
• Ctrl+Click 跳转定义、Go to References 查找引用，告别手动 grep