Ruff WASM 实战指南：在浏览器与 Node.js 中调用 Rust 实现的 Python Linter 与格式化器

Ruff WASM 实战指南：在浏览器与 Node.js 中调用 Rust 实现的 Python Linter 与格式化器

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

Ruff WASM 是把 Ruff（用 Rust 编写、以“极速”著称的 Python 代码检查与格式化工具）核心能力编译到 WebAssembly 之后的浏览器端 API 封装。本文以仓库内 crates/ruff_wasm/README.md 为主线，结合 crates/ruff_wasm/src/lib.rs 源码与 crates/ruff_wasm/tests/api.rs 测试用例，系统讲解如何通过 npm 包在 Vite、Web Worker 或 Node.js 中完成 Python 源码的 lint、格式化、AST/词法分析，并深入解读Workspace对象、配置格式、位置编码与诊断数据结构。读完本文，你将能在自己的前端项目里复刻官方 Playground 的核心能力，实现“浏览器内实时校验与格式化 Python 代码”。

⚠️ 实验性 API 警告

按 crates/ruff_wasm/README.md 的官方说明，本 API 仍属实验性质，随时可能变化；同时该 crate 属于 Ruff 工作区的内部组件，其 Rust API 不稳定，会频繁出现破坏性变更。引入前建议锁定版本号。

Ruff WASM 是什么：为什么把 Linter 编译成 WASM

Ruff 本体是纯 Rust 实现的 Python linter 与 formatter（参见 crates/ruff_linter 与 crates/ruff_python_formatter）。ruff_wasmcrate 借助wasm-bindgen把其中的检查（lint）、格式化（format）、解析（parse）等能力导出成可供 JavaScript/TypeScript 直接调用的接口，使其得以运行在浏览器等无法直接执行原生二进制的环境。

这样做的好处是明显的：

• 零后端依赖：校验与格式化全部在用户浏览器本地完成，源码不出浏览器，也不依赖远端 lint 服务；
• 实时反馈：配合 Monaco 等编辑器组件即可实现“边输入边检查边格式化”的 IDE 级体验，官方 Playground 正是这种架构的代表；
• 与 CLI 行为一致：由于底层复用的是 Ruff 同一套 lint 引擎、解析器与格式化器（见下方依赖列表），浏览器端结果与命令行运行 Ruff 高度一致。

从 crates/ruff_wasm/Cargo.toml 可以看到，它几乎聚合了 Ruff 的全部核心 crate：ruff_linter（规则引擎）、ruff_python_parser（解析器）、ruff_python_formatter（格式化器）、ruff_workspace（配置加载）、ruff_source_file（行列定位）等，编译产物类型为["cdylib", "rlib"]，其中cdylib正是为了生成 WASM 模块。

安装：针对不同运行时选择包

Ruff WASM 针对不同wasm-packtarget 发布了多个 npm 包（wasm-packtarget 含义可参考其官方文档中关于 Deployment 的说明）。当前仓库 README 列出的发布形态有三种：

运行时场景	npm 包名
Bundler（如 Vite / webpack）	@astral-sh/ruff-wasm-bundler
Web（直接