FreeBSD环境Helix结合LSP(Language Server Protocol)

备注

本文实践在FreeBSD上进行，和 Ubuntu环境Helix结合LSP(Language Server Protocol) 有较大差异

备注

本文基于gemini建议进行实践，虽然完成初始配置，但有可能并非准确和最优，有待后续继续实践。

由于没有按照 Helix集成LFS(language server) (按照官方文档实践)，所以可能并不完善。我准备后续再继续实践，目前先以本文方法继续学习。

和 Vim / neovim 不同，Helix对大多数主流语言，内置了"对接协议"，所以只需要将LSP程序安装到系统的 $PATH 中，Helix就能够自动识别并"握手成功"。也就是说，几乎无需配置，开箱即用。

Helix在源码中内置了一个 language.toml 默认文件，在这个文件中，已经为数百中编程语言定义好了"标准配置"。当你在系统中安装好了 py-pyright 或 gopls 之后，LSP程序位于 /usr/local/bin 。当使用Helix打开对应文件，如 .py 或 .go 文件，Helix就会自动扫描 $PATH ，发现对应的LSP程序，自动开启语法高亮，转跳定义和错误诊断。

安装LSP

python+yaml+ansible

先安装node.js，当前安装24.13.0(LTS)，实际版本以pkg search node和node.js官网为准

在FreeBS上使用pkg安装

# 在FreeBSD上，npm安装和node版本关联，分为两个包独立安装
pkg install node24 npm-node24

安装基于node的LSP

安装基于node的LSP

# Python 支持: 采用 npm 安装完成，这样能够获得最新的LSP版本
sudo npm install -g yaml-language-server pyright

安装基于node的LSP

# 也可以安装发行版提供的软件包，但是需要根据 pkg search pyright 来确定软件包名
# sudo pkg install py311-pyright
# YAML 支持（对 K8s 运维至关重要）
# sudo pkg install node-yaml-language-server

# Go 支持
sudo pkg install go gopls

# Rust 支持（如果你想研究 Helix 源码或 llm-ls）
sudo pkg install rust-analyzer

由于我也使用 Ansible ，所以先安装ansible，然后再配置helix能够解析ansible语法

安装Ansible

# 安装系统Python版本对应的Ansible
sudo pkg install py311-ansible

# 建议同时安装ansible语法和最佳实践检查器
sudo pkg install py311-ansible-lint

检查LSP是否安装成功:

检查LSP

hx --health python

hx --health yaml

这里提示信息有一些错误:

检查LSP时输出信息

$ hx --health python
Configured language servers:
  ✘ ty: 'ty' not found in $PATH
  ✘ ruff: 'ruff' not found in $PATH
  ✘ jedi: 'jedi-language-server' not found in $PATH
  ✘ pylsp: 'pylsp' not found in $PATH
Configured debug adapter: None
Configured formatter: None
Tree-sitter parser: ✓
Highlight queries: ✓
Textobject queries: ✓
Indent queries: ✓

$ hx --health yaml
Configured language servers:
  ✓ yaml-language-server: /usr/local/bin/yaml-language-server
  ✘ ansible-language-server: 'ansible-language-server' not found in $PATH
Configured debug adapter: None
Configured formatter: None
Tree-sitter parser: ✓
Highlight queries: ✓
Textobject queries: ✓
Indent queries: ✓

这里 python 相关的 LSP 工具如下:

LSP核心工具对比
工具名称	类型	核心优势	为什么 Helix 提示它
Pyright	LSP	微软开发，类型检查极其强大且速度飞快	SRE 首选:能帮你提前发现显存计算中的类型错误
Ruff	Linter/Formatter	用 Rust 编写，速度比传统工具快 10-100 倍	现代 Python 开发标配，集成了代码规范检查和格式化
Jedi	LSP	老牌、纯 Python 实现，对动态代码补全支持极好	兼容性极强，不依赖 Node.js 即可运行
PyLSP	LSP	插件式架构，集成了多种工具（如 Flake8，Mypy）	“全家桶”式的体验，传统选择
Ty	Helper	实验性的类型定义工具	较少见:通常是 Helix 配置文件中的可选依赖

Helix使用 Rust 开发，所以对Ruff支持非常丝滑，Ruff不仅能告诉你代码哪里写得不规范(如未使用的变量)，还能一键修复。Pyright是微软的VS Code团队维护，对复杂的库(如 Pytorch , NumPy, ROCm 相关库)有极佳的自动补全支持。

建议同时启用 Pyright+Ruff ，所以先安装 py311-ruff :

安装ruff

sudo pkg install py311-ruff

另外，针对yaml LSP建议同时安装ansible-language-server方便编辑 Ansible 的特殊YAML:

安装ansible-language-server

sudo npm install -g @ansible/ansible-language-server

最后，综上完成配置 ~/.config/helix/languages.toml :

配置 ~/.config/helix/languages.toml

[language-server.llm-ls]
command = "llm-ls"

[language-server.llm-ls.config]
# 指向你的 Ollama 地址
url = "http://192.168.6.200:11434/api/generate"
# 设定你模型名称
model = "qwen3.5-coder-30b-a3b-instruct-q4_k_m"
# 针对 Ollama 的提示词模板（FIM: Fill-In-the-Middle）
backend = "ollama"

# --- Python 配置 (支持多 GPU 脚本开发) ---
[[language]]
name = "python"
scope = "source.python"
# 同时启用 Pyright (类型检查) 和 Ruff (极速格式化/校验)
language-servers = [ "pyright", "ruff", "llm-ls" ]
auto-format = true

[language-server.pyright]
command = "pyright-langserver"
args = ["--stdio"]
config.python.analysis = { typeCheckingMode = "basic", autoSearchPaths = true }

[language-server.ruff]
command = "ruff"
args = ["server", "--preview"]

# --- go 语言配置 (支持 gopls + golangci-lint + llm-ls) ---
[[language]]
name = "go"
scope = "source.go"
# 激活 gopls (补全/定义), golangci-lint (校验), llm-ls (AI 续写)
# language-servers = [ "gopls", "golangci-lint-lsp", "llm-ls" ]
# 目前改为仅激活 gopls, llm-ls
language-servers = [ "gopls", "llm-ls" ]
auto-format = true
# 使用 Go 官方标准的 gofmt 进行格式化
formatter = { command = "gofmt" }

[language-server.gopls]
command = "gopls"
# 针对 SRE 开发场景优化 gopls 配置
[language-server.gopls.config]
usePlaceholders = true
completeUnimported = true
staticcheck = true
analyses = { unusedparams = true, unreachable = true }

#[language-server.golangci-lint-lsp]
#command = "golangci-lint-langserver"

# 我尝试 --out-format json 失败
# 另外，FreeBSD发行版提供的golangci-lint版本似乎和编译安装的golangci-lint-langserver版本不匹配，检查 :log-open 显示:
# golangci-lint-lsp err <- "jsonrpc2 handler: notification \"exit\" handling error: jsonrpc2: code -32601 message: method not supportd: exit\n"
# 所以我最终取消了 golangci-lint-lsp 支持，可能以后集成到Linux平台的CI系统中使用
# 
#[language-server.golangci-lint-lsp.config]
# 强制开启代码检查
#command = ["golangci-lint", "run", "--out-format", "json", "--issues-exit-code", "1"]

# --- 通用 YAML 配置 (Docusaurus / K8s / Docker) ---
[[language]]
name = "yaml"
scope = "source.yaml"
# 优先使用通用的 yaml-language-server
language-servers = [ "yaml-language-server", "llm-ls" ]
auto-format = true
# 强制缩进为 2 个空格 (YAML 标准)
indent = { tab-width = 2, unit = "  " }

[language-server.yaml-language-server]
command = "yaml-language-server"
args = ["--stdio"]
# 自动关联常见的 JSON Schema 以实现智能补全
[language-server.yaml-language-server.config.yaml]
completion = true
hover = true
[language-server.yaml-language-server.config.yaml.schemas]
"kubernetes" = "*.yaml"
"https://json.schemastore.org/github-workflow.json" = ".github/workflows/*.yaml"
"https://json.schemastore.org/docker-compose.json" = "docker-compose.yml"

# --- Ansible 专用配置 ---
[[language]]
name = "ansible"
scope = "source.ansible"
# 识别典型的 Ansible 文件名模式
file-types = ["yml", "yaml", { glob = "*/tasks/*.yml" }, { glob = "*/roles/*.yml" }, { glob = "playbook.yml" }]
# 当目录下存在这些文件时，激活 Ansible 模式
roots = ["ansible.cfg", ".ansible-lint", "inventory"]
# 叠加使用：Ansible 补全参数，YAML 校验语法
language-servers = [ "ansible-language-server", "yaml-language-server", "llm-ls" ]
indent = { tab-width = 2, unit = "  " }

[language-server.ansible-language-server]
command = "ansible-language-server"
args = ["--stdio"]

# --- 辅助工具：全局 Formatter (可选) ---
# 如果你安装了 prettier (npm install -g prettier)，可以作为通用格式化器
[language.formatter]
command = "prettier"
args = ["--parser", "yaml"]

注意，虽然上述配置已经完成，但是 hx --health ansible 还是有一些报错:

ansible相关的hx报错

Configured language servers:
  ✓ ansible-language-server: /usr/local/bin/ansible-language-server
  ✓ yaml-language-server: /usr/local/bin/yaml-language-server
Configured debug adapter: None
Configured formatter:
  ✓ /usr/local/bin/prettier
Tree-sitter parser: ✓
Highlight queries: ✘
Textobject queries: ✘
Indent queries: ✘

这是FreeBSD中Helix的 runtime 文件缺失或路径不匹配导致的。在Helix中， Hightlight , Textobject , Indent 这些功能依赖于对应的 .scm 查询文件。由于这里手动定义了 scope = "source.ansible" ，但是FreeBSD的 pkg 安装路径中可能没有安装 ansible 的查询文件。

由于ansible本质上是YAML，所以最快且最稳妥的方法是将YAML的查询文件"借"给ansible使用:

修复ansible查询文件

# 1. 创建用户的 runtime 目录
mkdir -p ~/.config/helix/runtime/queries/ansible

# 2. 将系统自带的 yaml 查询文件软链接到 ansible 目录下
ln -s /usr/local/share/helix/runtime/queries/yaml/highlights.scm ~/.config/helix/runtime/queries/ansible/highlights.scm
ln -s /usr/local/share/helix/runtime/queries/yaml/indents.scm ~/.config/helix/runtime/queries/ansible/indents.scm
ln -s /usr/local/share/helix/runtime/queries/yaml/textobjects.scm ~/.config/helix/runtime/queries/ansible/textobjects.scm

go

安装 gopls :

安装 gopls`

sudo pkg install go gopls

此时检查 hx --health go 有如下提示:

检查go环境有部分报错

Configured language servers:
  ✓ gopls: /usr/local/bin/gopls
  ✘ golangci-lint-lsp: 'golangci-lint-langserver' not found in $PATH
Configured debug adapter:
  ✘ 'dlv' not found in $PATH
Configured formatter: None
Tree-sitter parser: ✓
Highlight queries: ✓
Textobject queries: ✓
Indent queries: ✓

这里 dlv 是调试工具，可以在Helix中设置断电、单步执行代码，所以补充安装 delve :

修复 golangci-lint 报错

# 安装核心工具
sudo pkg install golangci-lint

# 安装golangci-lint-langserver
go install github.com/nametake/golangci-lint-langserver@latest

这里 go install 需要访问github.com，所以需要配置Go程序代理服务器 :

设置go socks代理

# go设置代理需要设置环境变量以及git的代理

export http_proxy=socks5h://127.0.0.1:1080
export https_proxy=socks5h://127.0.0.1:1080

git config --global http.proxy socks5h://127.0.0.1:1080

需要注意，通过 go install 安装的二进制软件位于 ~/go/bin 目录，所以需要添加到环境变量中以确保能够找到 golangci-lint-langserver 命令:

设置GO程序路径

cat << 'EOF' >> ~/.shrc
PATH=$PATH:$HOME/go/bin
EOF

完成上述安装配置之后，再次执行 hx --health go 就能看到正确的设置:

正确的设置输出信息

Configured language servers:
  ✓ gopls: /usr/local/bin/gopls
  ✓ golangci-lint-lsp: /home/admin/go/bin/golangci-lint-langserver
Configured debug adapter:
  ✓ /usr/local/bin/dlv
Configured formatter: None
Tree-sitter parser: ✓
Highlight queries: ✓
Textobject queries: ✓
Indent queries: ✓

rust

安装 Rust :

在FreeBSD上通过pkg安装rust

sudo pkg install rust

安装LSP:

安装rust的LSP

sudo pkg install rust-analyzer