本文介绍如何搭建 Claude Context 的本地开发环境，其核心工作流基于 pnpm monorepo。你将学会使用 pnpm build:core 等脚本构建各包，通过 dev:mcp 等命令进入开发模式，并了解 GitHub Actions 如何在 Ubuntu 和 Windows 上对 Node 20、22、24 版本进行跨平台测试。最后，文章将指导你完成核心包到 npm 以及 VSCode 扩展的发布，并分享如何利用内置脚本测量构建性能。

Claude Context 开发环境搭建：Monorepo 构建、测试与发布流程

对于希望参与 Claude Context 开发或在其基础上进行二次开发的工程师而言，理解其标准的 monorepo 工作流是第一步。该项目采用 pnpm workspace 管理多个相互关联的包，确保了代码共享的一致性和构建发布流程的自动化。

1. 项目 Monorepo 结构解析

Claude Context 的代码库采用典型的 monorepo 布局，所有共享的配置文件（如 TypeScript、ESLint）位于根目录，而独立的功能模块作为 packages 存在。这种结构的核心由根目录的 pnpm-workspace.yaml 文件定义：

packages:
  - packages/*
  - examples/*

这行配置告诉 pnpm，packages/ 和 examples/ 目录下的每一个子目录都是一个独立的、可管理的 npm 包。实际目录结构如下：

packages/core：对应 @zilliz/claude-context-core，负责语义索引的核心引擎。
packages/mcp：对应 @zilliz/claude-context-mcp，是提供 MCP 协议能力的服务器。
packages/vscode-extension：对应 semanticcodesearch，即 VSCode 扩展。
packages/chrome-extension：Chrome 浏览器扩展。
examples/basic-usage：基础使用示例。

根目录的 package.json 中 engines 字段明确了开发所需的环境版本：Node.js >= 20.0.0 和 pnpm >= 10.0.0。

2. 构建脚本详解

所有构建命令都定义在根 package.json 的 scripts 字段中，使用 pnpm 的 --filter 参数精确作用于目标包。

2.1 单包构建

# 构建核心引擎
pnpm build:core
# 等同于: pnpm --filter @zilliz/claude-context-core build

# 构建 MCP 服务器
pnpm build:mcp
# 等同于: pnpm --filter @zilliz/claude-context-mcp build

# 编译 VSCode 扩展
pnpm build:vscode
# 等同于: pnpm --filter semanticcodesearch compile

# 构建 Chrome 扩展 (在 build 脚本中触发)
pnpm build

pnpm build 命令会先构建所有非 examples 的包（packages/*），随后再构建示例包（examples/*），确保了依赖顺序正确。

2.2 全量构建

执行 pnpm build 将按照依赖关系构建整个 monorepo。通常，在克隆仓库并执行 pnpm install 后，首要步骤就是运行此命令。

3. 开发模式与热更新

为了提升开发效率，项目为每个主要包提供了 watch 模式，文件修改后会自动触发增量编译。

# 启动所有包的 dev 模式
pnpm dev

# 或仅启动特定包的 watch 模式
pnpm dev:core   # 监听核心引擎代码变化
pnpm dev:mcp    # 监听 MCP 服务器代码变化
pnpm dev:vscode # 监听 VSCode 扩展代码变化

这些命令会在终端中持续运行，非常适合在开发、调试时配合使用。

4. 持续集成 (CI) 测试流程

项目的质量通过 GitHub Actions 进行保障，配置文件位于 .github/workflows/ci.yml。其核心策略是在多种操作系统和 Node.js 版本组合下运行测试。

4.1 测试矩阵

CI 流程使用 strategy.matrix 定义了一个测试矩阵：

操作系统 (os)：ubuntu-latest, windows-latest
Node.js 版本 (node-version)：20.x, 22.x, 24.x

这意味着每次代码推送或 PR 都会在 2 x 3 = 6 种不同的环境中并行执行构建验证。

4.2 CI 流程关键步骤

检出代码与安装 pnpm。
针对 Windows 的特殊处理：执行 git config --global core.autocrlf false 以统一换行符，避免跨平台构建问题。
安装依赖：使用 pnpm install --frozen-lockfile 确保安装的依赖版本与锁文件完全一致。
执行全量构建：pnpm build。
验证构建产物：在 Unix 系统和 Windows 系统上分别使用 ls 和 Get-ChildItem 命令检查 packages/core/dist 和 packages/mcp/dist 目录是否存在。

这种矩阵策略确保了 Claude Context 在主流开发平台和活跃的 Node.js 版本上都能稳定构建和运行。

5. 发布流程

发布流程由 .github/workflows/release.yml 管理，当推送以 v 或 c 开头的 git tag 时自动触发。

5.1 npm 包发布

在 CI 环境中配置好 NPM_TOKEN 密钥后，发布命令如下：

# 发布核心引擎包
pnpm release:core
# 等同于: pnpm --filter @zilliz/claude-context-core... run build && pnpm --filter @zilliz/claude-context-core publish --access public --no-git-checks

# 发布 MCP 服务器包
pnpm release:mcp
# 等同于: pnpm --filter @zilliz/claude-context-mcp... run build && pnpm --filter @zilliz/claude-context-mcp publish --access public --no-git-checks

命令中的 ... 语法确保会先构建该包及其所有工作区依赖。

5.2 VSCode 扩展发布

发布 VSCode 扩展需要 VS Code Marketplace 的 Personal Access Token (VSCE_PAT)。命令为：

pnpm release:vscode

这个命令会依次执行：构建核心包、使用 webpack 打包扩展、最后调用 vsce release 进行发布。

6. 构建性能基准测试

项目提供了一个内置脚本 scripts/build-benchmark.js，用于测量各包的构建时间。通过运行：

pnpm benchmark

脚本会按顺序执行 pnpm clean、pnpm build:core、pnpm build:mcp、pnpm build:vscode 和 Chrome 扩展的构建，并记录每个步骤的耗时。

完成后，测量结果（包括时间戳、平台、Node 版本和各步骤详情）会追加到根目录的 build-benchmark.json 文件中，最多保留最近 10 次记录。这对于监控构建性能变化非常有用。

FAQ

Q: Windows 开发环境下需要特别注意什么？ A: 强烈建议在克隆仓库后立即运行 git config core.autocrlf false，以确保与 Linux/macOS 开发者的换行符一致，避免潜在的构建或测试问题。

Q: 如何只构建一个包并发布到 npm？ A: 使用 pnpm release:core 或 pnpm release:mcp 命令。它会自动处理依赖构建并执行发布，确保你不会遗漏任何构建步骤。

Q: CI 测试失败，提示某个包构建产物找不到，如何排查？ A: 首先在本地执行 pnpm clean && pnpm build 确认能否复现。如果本地成功，检查 CI 日志中特定矩阵环境（如 Windows + Node 24.x）的构建输出，看是否有平台相关的错误。确保所有依赖的构建脚本在 package.json 中定义正确。

Claude Context 开发环境搭建：Monorepo 构建、测试与发布流程 #

1. 项目 Monorepo 结构解析 #

2. 构建脚本详解 #

2.1 单包构建 #

2.2 全量构建 #

3. 开发模式与热更新 #

4. 持续集成 (CI) 测试流程 #

4.1 测试矩阵 #

4.2 CI 流程关键步骤 #

5. 发布流程 #

5.1 npm 包发布 #

5.2 VSCode 扩展发布 #

6. 构建性能基准测试 #

FAQ #