5分钟接入Harper：给你的VS Code装上不联网的语法检查器

为什么选Harper？

刚才介绍了 Automattic 开源的 Harper 语法检查器。这篇教程带你从零开始，把它装进 VS Code，享受离线、隐私优先的实时语法纠错。

**核心思路**：Harper 的核心是一个 Rust 编译的 WASM 模块，所有处理在本地完成。VS Code 插件只需下载这个模块，无需任何网络请求。

Step 1: 安装 VS Code 插件

打开 VS Code，按 `Ctrl+Shift+X`（Mac: `Cmd+Shift+X`）打开扩展市场，搜索 “Harper”。

找到由 Automattic 官方发布的 `harper-ls`，点击安装。安装完成后 VS Code 右下角会出现 Harper 的状态图标。

Step 2: 验证安装

新建一个文件，写入一段有语法错误的英文：

He go to the store yesterday and buy three apple.

保存文件后，Harper 会用波浪线标注三个错误：

– `go` → 应改为 `went`（过去式不一致）

– `buy` → 应改为 `bought`（时态错误）

– `apple` → 应改为 `apples`（单复数不一致）

如果看到了这些标注，说明 Harper 已正常工作。

Step 3: 调整检查规则

打开 VS Code 设置（`Ctrl+,`），搜索 `harper`。你可以自定义：

{
  "harper.linters.spell_check": true,
  "harper.linters.repeated_words": true,
  "harper.linters.spaces": true,
  "harper.dialect": "American"
}

关键选项说明：

– `harper.dialect`：可选 `American`、`British`、`Canadian`、`Australian`

– `harper.linters.spell_check`：开启拼写检查

– `harper.linters.repeated_words`：检测重复单词（如 “the the”）

Step 4: 集成到项目 CI/CD

Harper 还提供了命令行工具，可以集成到 GitHub Actions 中：

# 安装 harper-cli
cargo install harper-cli

# 检查 Markdown 文件
harper-cli lint "docs/**/*.md"

# 输出 JSON 格式（方便 CI 解析）
harper-cli lint "docs/**/*.md" --json

在 `.github/workflows/lint.yml` 中添加：

- name: Run Harper
  run: harper-cli lint "docs/**/*.md" --json > harper-report.json

常见踩坑与解决方案

在实际使用 Harper 的过程中，有几个高频问题值得注意：

问题一：检查结果不准确

Harper 在英文语法检查上的准确率约为 85-90%，低于 Grammarly（95%+）。遇到误报时，你可以在 VS Code 中使用 `Ctrl+.`（Mac: `Cmd+.`）快速禁用特定规则：

{
  "harper.linters.rule_id": false
}

问题二：大文件性能下降

超过 5000 词的单个文件会导致 WASM 模块内存压力。建议将长文档拆分为章节文件，或者使用 `harper-cli` 的 `–chunk-size` 参数分块处理。

问题三：专业术语误报

如果你写的是技术文档，”kubectl”、”namespace” 等术语会被标记为拼写错误。在项目根目录创建 `.harperignore` 文件：

kubectl
namespace
microservice

生产环境最佳实践

如果你计划在团队中推广 Harper，以下配置建议可以帮你少走弯路：

统一配置文件。在项目根目录放置 `harper.toml`，团队成员 clone 代码后自动应用相同的检查规则，避免”我的机器上没问题”的困扰。

CI 集成做渐进式引入。先在 CI 中以 warning 模式运行（`harper-cli lint –level warning`），等团队适应后再升级到 error 模式。直接上 error 会导致大量构建失败，反而降低采纳意愿。

定期更新 WASM 核心。Harper 的语法规则库在持续改进，每月至少更新一次插件版本。Rust 核心的更新通常包含新的语法检测规则和性能优化。

与其他工具的集成

Harper 的 WASM 核心使其可以嵌入到各种工具中。以下是一些社区维护的集成方案：

Neovim 集成。通过 `null-ls` 或 `none-ls` 插件，可以将 Harper 作为 LSP 诊断源：

local null_ls = require("null-ls")
null_ls.setup({
  sources = {
    null_ls.builtins.diagnostics.harper,
  },
})

Git pre-commit hook。阻止包含语法错误的提交进入仓库：

#!/bin/bash
# .git/hooks/pre-commit
harper-cli lint "$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')" --json
if [ $? -ne 0 ]; then
  echo "❌ Harper found grammar issues. Please fix before committing."
  exit 1
fi

Obsidian 插件。如果你是 Obsidian 用户，在社区插件市场搜索 “Harper” 即可安装。所有语法检查在本地完成，你的笔记内容永远不会离开 Obsidian 的本地 vault。

**速成效果**：5分钟内，你获得了一个完全离线、零延迟、不发送任何数据到第三方的语法检查环境。对于需要频繁撰写英文技术文档、博客文章和代码注释的开发者来说，这意味着从此不再需要在”便利”和”隐私”之间二选一。

👇 关注不错过

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn