- 开发工具
【免费下载链接】tree-sitter
An incremental parsing system for programming tools
本文基于仓库文档 docs/src/creating-parsers/6-publishing.md 展开，面向已经完成语法（Grammar）开发并准备交付给下游用户的 Tree-sitter 语法作者。你将掌握如何用
tree-sitter version一键同步各语言绑定的版本号、如何按语义化版本规则规划发布节奏，以及从打 tag 到推送、再到借助 CI 工作流自动发布到 GitHub、crates.io、npm 与 PyPI 的完整实操路径。
发布前的准备：把语法送到用户所在的生态
Tree-sitter 语法的消费者遍布不同技术栈：Rust 开发者从 crates.io 拉取、JavaScript/TypeScript 开发者通过 npm 安装、Python 开发者依赖 PyPI，而 C/C++ 及其他语言用户则可能直接从 GitHub 源码构建。因此官方文档明确建议：当你的解析器达到可供消费者使用的稳定状态后，强烈推荐同时发布到 GitHub、crates.io（Rust）、npm（JavaScript）和 PyPI（Python），这样能最大程度降低他人发现与使用你语法的门槛。
如果你的语法托管在 GitHub 上，还可以利用官方提供的**可复用工作流（reusable workflows）**来自动化发布过程。这套 GitHub Actions 会在 CI 中自动完成重新生成与发布，前提是你为各个注册表正确配置了所需的令牌（token）。官方文档给出了真实示例：Python 语法仓库（tree-sitter-python）的.github/workflows/publish.yml就是这套工作流的落地范例。这意味着你本地只需要执行“改版本号 → 提交 → 打 tag → 推送”，剩下的发布动作全部交给 CI 完成。
端到端发布流程：五步完成一次发布
官方文档给出了从零到一的完整发布清单，这也是每次发版都应遵循的标准动作：
- 升级版本号：用
tree-sitter version把版本号设置到目标值。例如发布1.0.0时运行：tree-sitter version 1.0.0该命令会同步更新仓库内所有涉及版本号的文件（详见下一节）。
- 提交变更：确保工作目录干净后提交，例如：
git commit -am "Release 1.0.0" - 打标签：为提交打上语义化版本标签：
git tag -- v1.0.0 - 推送提交与标签：假设你在
main分支、远端名为origin：git push --tags origin main - （可选）自动发布：如果你已经配置了 GitHub 发布工作流，本次推送触发 CI 后，语法会被自动发布到 GitHub、crates.io、npm 和 PyPI，无需任何手动上传操作。
这套流程的关键在于：标签（tag）与版本号必须严格对应，因为后续的语义化版本比较、依赖解析以及 CI 触发都以 tag 为锚点。
深入tree-sitter version：一个命令同步全部绑定
tree-sitter version是发布流程的核心命令，其完整说明见 docs/src/cli/version.md，底层实现位于 crates/cli/src/version.rs。它的职责是：把语法版本号在多个语言绑定之间保持一致——手动同步这些文件繁琐且极易出错，该命令正是为此而生。
会更新哪些文件
命令运行时会遍历以下文件（存在才更新，不存在则跳过）：
| 文件 | 说明 |
|---|---|
tree-sitter.json | 语法的统一描述文件，版本号的权威来源 |
Cargo.toml/Cargo.lock | Rust（crates.io）绑定 |
package.json/package-lock.json | JavaScript（npm）绑定 |
Makefile | C 绑定的 make 构建版本号（VERSION变量） |
CMakeLists.txt | CMake 构建配置中的VERSION |
pyproject.toml | Python（PyPI）绑定 |
build.zig.zon | Zig 构建绑定（从源码结构看，该命令同样支持 Zig 包管理） |
三种调用形态
# 1. 打印当前版本（不修改任何文件） tree-sitter version # 2. 直接指定目标版本（等价于发布别名） tree-sitter version 1.0.0 # 别名：publish # 3. 基于当前版本自动递增 tree-sitter version --bump patch tree-sitter version --bump minor tree-sitter version --bump major其中--bump的递增逻辑在 version.rs 中实现，遵循标准语义化版本规则：patch只增加补丁号，minor增加次版本号并将补丁号清零，major增加主版本号并将次版本号与补丁号一并清零。
需要注意的细节
- 版本号权威来源：
tree-sitter version直接读取当前目录下tree-sitter.json中的metadata.version作为基准（参见 loader.rs 中TreeSitterJSON的结构定义），再向各绑定文件扩散。 - 外部工具依赖：更新
Cargo.toml/Cargo.lock需要本机安装cargo（update_cargo_lock会调用cargo generate-lockfile --offline）；更新package-lock.json需要本机安装npm（会调用npm install --package-lock-only）。缺少对应工具时该文件会静默跳过，其余文件照常更新。 - 降版本会警告：如果新版本号低于当前版本，命令会输出警告提示“正在将版本从 X 回退到 Y”，避免误操作。
- 指定语法路径：语法不在当前目录时，可用
-p/--grammar-path <PATH>指定包含语法的目录。 - 多语法仓库：若
tree-sitter.json中声明了多个 grammar（grammars数组长度大于 1），Makefile 的版本更新会定位到common/common.mak而非根目录Makefile，说明该命令对 monorepo 形态的多语法仓库同样有支持。
各语言绑定的版本号都长什么样
tree-sitter version之所以能同步这么多文件，是因为tree-sitter init生成的模板（见 crates/cli/src/templates）为每种绑定都预留了统一的版本号占位符：
- npm 绑定（templates/package.json）：
"version": "PARSER_VERSION"，发布到 npm 的包名为tree-sitter-PARSER_NAME，并声明了node-addon-api、node-gyp-build等构建依赖。 - crates.io 绑定（templates/_cargo.toml）：
version = "PARSER_VERSION"，同时包含tree-sitter-language、cc等依赖与categories/keywords元数据。 - PyPI 绑定（templates/pyproject.toml）：
version = "PARSER_VERSION"，要求requires-python = ">=3.10"，并配置了 cibuildwheel 以产出多平台 wheel。 - C 绑定（templates/makefile）：
VERSION := PARSER_VERSION，同时用于生成.pc文件与动态库的 SONAME 版本。 - 仓库中还包含
pom.xml（Java/Maven）、binding.gyp、root.zig（Zig）、setup.py等模板，覆盖了更广泛的分发渠道。
由此可见，tree-sitter version的价值在于：一次修改，全生态一致，这正是多语言语法库能够长期健康维护的基础设施保障。
语义化版本：下游用户能否安全升级的分水岭
发布语法的核心纪律是严格遵循语义化版本（Semantic Versioning）。这保证消费者可以预测性地升级依赖，同时让既有集成——包括查询（queries）、树遍历代码、节点类型检查——在升级后仍然按预期工作。
官方文档给出的规则非常明确：
- 主版本号（major）：当语法的节点类型或结构发生不兼容变更时递增。例如移除/重命名某个节点类型、改变子节点顺序，都会破坏下游对语法树的既有假设。
- 次版本号（minor）：新增节点类型或模式且保持向后兼容时递增。新增的节点不会破坏旧查询，因此属于兼容性变更。
- 补丁版本号（patch）：修复 bug 且不改变语法结构时递增。这类变更对下游完全透明。
0.y.z 阶段的特殊策略
对于处于0.y.z（零版本）阶段的语法，语义化版本的规则在技术上有所放宽——理论上 0.x 期间任何 minor 变更都可视为不兼容。但官方文档特别提醒：如果你的语法已经有用户，建议以更保守的态度对待版本变更：
- 把补丁版本（
z）的变更视为次版本（minor）变更来对待； - 把次版本（
y）的变更视为主版本（major）变更来对待。
这样在 pre-1.0 阶段依然能为既有用户维持稳定性，确保下游用户升级时不会因版本号“显得无害”而导致查询意外失效。换句话说：版本号不只描述差异，还承载着对兼容性的承诺，越早建立严格的发版纪律，生态内的信任就越牢固。
发布后的验证
发布完成后，建议做以下收尾确认：
- 检查 tag 是否与
tree-sitter version输出的版本号一致（git tag --list）； - 确认 CI 工作流被正确触发，并在 GitHub、crates.io、npm、PyPI 各注册表检查产物是否已就位；
- 从各注册表安装一遍新版本，跑通语法测试（
tree-sitter test）与高亮/标签查询测试，确认下游集成的查询与节点类型断言未被破坏。
至此，你的语法便完成了从本地仓库到多生态分发渠道的正式交付。后续迭代中，只需遵循“语义化版本决定改动类型、tree-sitter version统一版本、tag 触发 CI 自动发布”这一固定节奏，即可持续、稳定地维护你的语法包。
参考文档与源码
- 本文主体文档：docs/src/creating-parsers/6-publishing.md
tree-sitter version命令文档：docs/src/cli/version.md- 版本同步命令实现：crates/cli/src/version.rs
tree-sitter.json结构定义：crates/loader/src/loader.rs- 各语言绑定模板：crates/cli/src/templates
- 开发工具
【免费下载链接】tree-sitter
An incremental parsing system for programming tools
相关推荐
wgpu 发布流程实战指南：从版本号到 crates.io 的大版本与小版本发布全流程
wgpu 发布流程实战指南：从版本号到 crates.io 的大版本与小版本发布全流程 本篇指南基于 docs/release checklist.md htt
图形学3D渲染a2ui 多语言生态发布全流程指南：从 pub.dev、npm 到 PyPI 的版本发布实战
a2ui 多语言生态发布全流程指南：从 pub.dev、npm 到 PyPI 的版本发布实战 a2ui 是一个跨语言、跨渲染框架的 Agent UI 协议项目，
人工智能AI AgentAI 应用前端UI组件OmniRoute 发布检查清单实践指南：从版本号到 npm 制品的安全发布流程
OmniRoute 发布检查清单实践指南：从版本号到 npm 制品的安全发布流程 本指南围绕 OmniRoute 官方发布检查清单（英文原版见 docs/ops
LLM 网关人工智能API网关后端前端桌面应用
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
