企业官网建设流程全解析

Scalar 云 Agent 快速上手指南：在 Scalar Monorepo 中安装、运行与测试全流程

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar

本文面向需要在 Scalar 开源仓库（一个集 REST API 客户端、API Reference 文档渲染与 OpenAPI/Swagger 工具链于一体的 pnpm monorepo）中快速完成依赖安装、启动开发服务、运行单元测试与 E2E 测试的云端 Agent 与开发者。读完本文，你将掌握从零搭建环境、按包启动 dev server、跑通 Vitest 单元测试与 Playwright E2E 测试、并复刻 CI 校验流程的完整操作路径。

前置条件与环境确认

在动手之前，先确认本机工具链版本，这是整个 runbook 的起点：

• Node.js：v24（仓库根目录的 .nvmrc 明确写有v24，可用nvm use自动切换）；
• 包管理器：pnpm（^10.16.1及以上）。根 package.json 的engines.pnpm与packageManager字段（pnpm@10.16.1）都锁定了该版本；
• 首次搭建环境时依次执行：

pnpm install pnpm build:packages

其中pnpm build:packages是后续开发的前提——它会通过 turbo 构建packages/**下全部包（见根 package.json 中build:packages脚本），确保 workspace 内各包间的本地依赖可用。

为什么是 monorepo？根 pnpm-workspace.yaml 声明了packages/**、integrations/**、examples/**、projects/**与tooling/scripts等工作区，并统一通过catalogs管理 Vue、Vite、Vitest、React 等共享依赖版本，这也是各包 dev 脚本可以直接使用workspace:*依赖的原因。

1. 根目录 / Monorepo 通用命令

启动开发服务

与单仓库项目不同，本仓库没有单一的根级pnpm dev，每个包都自带独立的 dev script。按需启动特定包：

pnpm --filter @scalar/api-client dev pnpm --filter api-reference dev pnpm --filter components dev

--filter既可以匹配完整的包名（如@scalar/api-client），也可以匹配简写（如api-reference）。

构建

pnpm build:packages # 构建所有 packages（dev 前必做） pnpm build:integrations # 构建所有 integrations pnpm clean:build # 清理、重装依赖并重新构建

以clean:build为例，根 package.json 将其实现为pnpm clean && pnpm install && pnpm build:packages，其中clean会移除各包的dist、.turbo、.nuxt、.next、target与node_modules产物。

Lint 与格式化

pnpm lint:check # 检查 lint（biome，仅报 error 级） pnpm lint:fix # 自动修复 lint pnpm format:check # 检查格式化（prettier + biome） pnpm format # 应用格式化 pnpm types:check # TypeScript 类型检查（turbo 并行）

从根 package.json 可以看到，lint 基于@biomejs/biome（biome lint --diagnostic-level=error），类型检查则通过turbo types:check在工作区各包间并行执行。

2. Packages 开发（packages/*）

运行某个包的 dev server

进入包目录后执行：

cd packages/<package-name> pnpm dev

仓库内常见包的入口与说明如下表（依据各包 package.json 的 scripts 字段整理）：

单元测试（Vitest）

仓库统一使用 Vitest 作为单元测试框架（vitest版本由 pnpm-workspace.yaml 的 catalog 统一管理）：

pnpm test # 运行全部测试（packages + integrations） pnpm vitest packages/* # 仅 packages pnpm vitest packages/api-client # 仅某个包 pnpm vitest packages/api-client --run # 单次运行，不进入 watch 模式 pnpm test your-test-name # 按测试名过滤

注意：部分测试依赖测试服务器。某些测试用例需要@scalar/void-server（端口 5052）与proxy-scalar-com（端口 5051）在线，请在独立终端先启动：

pnpm script run test-servers

随后等待端口就绪：

pnpm script wait -p 5051 5052

这里的pnpm script映射到根 package.json 中的"script": "pnpm --filter @scalar-internal/build-scripts start"，即 tooling/scripts 内的内部构建脚本工具集。

3. Integrations 集成包（integrations/*）

运行集成开发服务器

Scalar 为多种后端框架提供了官方集成，启动方式同样是--filter：

pnpm --filter @scalar/express-api-reference dev pnpm --filter @scalar/fastify-api-reference dev pnpm --filter @scalar/nuxt dev pnpm --filter @scalar/nextjs-api-reference dev

集成测试

pnpm vitest integrations/* # 全部集成测试 pnpm vitest integrations/express # 单个集成测试

跨语言集成的特殊要求（这是最容易踩坑的边界条件）：

• Python 集成（如 FastAPI、Django Ninja，位于 integrations/fastapi、integrations/django-ninja）：需要Python 3.11，在集成目录内执行python run_tests.py；
• Rust / Java / .NET 集成（如 integrations/rust、integrations/java、integrations/dotnet）：拥有独立的 CI job，通常使用各自的原生工具链运行（cargo、mvn、dotnet），不依赖 pnpm 的 vitest 体系。

4. E2E 与 Playwright

API Reference E2E

cd packages/api-reference pnpm test:e2e # 本地运行（需要 Playwright 浏览器） pnpm test:e2e:ci # CI 模式 pnpm test:e2e:update-snapshots # 更新截图快照

从 packages/api-reference/package.json 可见，本地 E2E 实际命令为PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:5001/ playwright test——即通过 WebSocket 连接到本地 Playwright 浏览器服务，另有test:e2e:cdn与TEST_MODE=CDN用于 CDN 快照测试。

Components E2E（Storybook）

cd packages/components pnpm test:e2e # 本地 pnpm test:e2e:ci # CI 模式（会设置 CI=1） pnpm test:e2e:update # 更新快照

Nuxt E2E

pnpm --filter @scalar/nuxt test:e2e

通用提示：本地运行 Playwright 时通过PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:5001/连接浏览器；CI 模式下则无需该变量，直接使用 Playwright 内置浏览器。

5. 环境变量与工作流

关键环境变量

• CI=1：模拟 CI 行为，部分测试服务器与 Playwright 运行会据此切换模式（如 packages/components/package.json 中test:e2e:ci即为CI=1 playwright test）；
• NODE_OPTIONS：openapi-parser的测试需要NODE_OPTIONS=--max_old_space_size=8192，用于处理大规格 OpenAPI 文档（参考 packages/openapi-parser）；
• TEST_MODE=CDN：用于api-reference的 CDN 快照测试，配合pnpm test:e2e:cdn使用。

常用内部脚本（tooling/scripts）

pnpm script run test-servers # 启动 void-server + proxy-scalar-com pnpm script wait -p 5051 5052 # 等待指定端口就绪 pnpm script generate-readme # 重新生成集成包的 README

关于 Feature Flags

从当前仓库结构看，本代码库不使用 feature flag 机制。行为差异统一通过包的 options（如@scalar/api-client的配置项）、OpenAPI 规范扩展（x-扩展字段）或上文所述的环境变量来控制。

6. Projects 与 Examples

• proxy-scalar-com（Go）：位于 projects/proxy-scalar-com，启动命令为cd projects/proxy-scalar-com && go run main.go，监听5051端口；
• Examples（examples/*）：每个示例都有独立的pnpm dev，例如 examples/web、examples/react，可直接作为各框架接入方式的参考样板（如 examples/nestjs 下的 express/fastify 两种接入示例）。

7. 本地复刻 CI（CI Parity）

要在本地近似还原 CI 的完整检查链路，按以下顺序执行：

pnpm install pnpm build:packages pnpm vitest packages/* --silent pnpm vitest integrations/* --silent pnpm types:check pnpm lint:check pnpm format:check

这套流程依次覆盖：依赖安装 → 全量包构建 → 单元测试（packages）→ 集成测试 → 类型检查 → lint → 格式化校验，与根 package.json 中test（turbo 并行跑各工作区测试）及types:check的语义保持一致，是提交前自检与 Agent 排障的标准基线。

8. 维护这份 Skill 文档的约定

当你在开发中发现新的测试技巧、runbook 步骤或环境要求时，建议按以下原则更新本技能文档（当前存放位置为.agents/skills/cloud-agents-starter/SKILL.md）：

1. 归类到合适的小节：根目录命令、packages、integrations、E2E、环境与工作流；
2. 使用可直接复制的具体命令：必须包含确切的包名与路径；
3. 记录边界条件：例如 "Python 集成需要 Python 3.11"、"openapi-parser 需要 NODE_OPTIONS" 这类容易踩坑的细节；
4. 保持最小化：只保留 Agent 快速运行与测试所需的内容；
5. 标注依赖关系：如果某一步依赖前置步骤（如 package 测试依赖 test-servers），必须明确写出先后关系。

常见问题速查

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar