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.jsv24仓库根目录的 .nvmrc 明确写有v24可用nvm use自动切换包管理器pnpm^10.16.1及以上。根 package.json 的engines.pnpm与packageManager字段pnpm10.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 # 构建所有 packagesdev 前必做 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 # 检查 lintbiome仅报 error 级 pnpm lint:fix # 自动修复 lint pnpm format:check # 检查格式化prettier biome pnpm format # 应用格式化 pnpm types:check # TypeScript 类型检查turbo 并行从根 package.json 可以看到lint 基于biomejs/biomebiome lint --diagnostic-levelerror类型检查则通过turbo types:check在工作区各包间并行执行。2. Packages 开发packages/*运行某个包的 dev server进入包目录后执行cd packages/package-name pnpm dev仓库内常见包的入口与说明如下表依据各包 package.json 的 scripts 字段整理包dev 命令说明api-clientpnpm dev运行vite ./playground/modal即 API 客户端 playgroundv2:webapi-referencepnpm devAPI Reference 主 playgroundvite默认配置componentspnpm devStorybook 开发服务器端口5100mock-serverpnpm devMock Server playgroundvoid-serverpnpm devHTTP 镜像服务器端口5052galaxypnpm dev通过scalar/cli以 watch 模式托管 OpenAPI 示例文档见 packages/galaxy/package.json 中pnpx scalar/cli document serve ./src/documents/3.1.yaml --watch单元测试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 为多种后端框架提供了官方集成启动方式同样是--filterpnpm --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.pyRust / Java / .NET 集成如 integrations/rust、integrations/java、integrations/dotnet拥有独立的 CI job通常使用各自的原生工具链运行cargo、mvn、dotnet不依赖 pnpm 的 vitest 体系。4. E2E 与 PlaywrightAPI Reference E2Ecd 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_ENDPOINTws://127.0.0.1:5001/ playwright test——即通过 WebSocket 连接到本地 Playwright 浏览器服务另有test:e2e:cdn与TEST_MODECDN用于 CDN 快照测试。Components E2EStorybookcd packages/components pnpm test:e2e # 本地 pnpm test:e2e:ci # CI 模式会设置 CI1 pnpm test:e2e:update # 更新快照Nuxt E2Epnpm --filter scalar/nuxt test:e2e通用提示本地运行 Playwright 时通过PW_TEST_CONNECT_WS_ENDPOINTws://127.0.0.1:5001/连接浏览器CI 模式下则无需该变量直接使用 Playwright 内置浏览器。5. 环境变量与工作流关键环境变量CI1模拟 CI 行为部分测试服务器与 Playwright 运行会据此切换模式如 packages/components/package.json 中test:e2e:ci即为CI1 playwright testNODE_OPTIONSopenapi-parser的测试需要NODE_OPTIONS--max_old_space_size8192用于处理大规格 OpenAPI 文档参考 packages/openapi-parserTEST_MODECDN用于api-reference的 CDN 快照测试配合pnpm test:e2e:cdn使用。常用内部脚本tooling/scriptspnpm 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 与 Examplesproxy-scalar-comGo位于 projects/proxy-scalar-com启动命令为cd projects/proxy-scalar-com go run main.go监听5051端口Examplesexamples/*每个示例都有独立的pnpm dev例如 examples/web、examples/react可直接作为各框架接入方式的参考样板如 examples/nestjs 下的 express/fastify 两种接入示例。7. 本地复刻 CICI 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 中testturbo 并行跑各工作区测试及types:check的语义保持一致是提交前自检与 Agent 排障的标准基线。8. 维护这份 Skill 文档的约定当你在开发中发现新的测试技巧、runbook 步骤或环境要求时建议按以下原则更新本技能文档当前存放位置为.agents/skills/cloud-agents-starter/SKILL.md归类到合适的小节根目录命令、packages、integrations、E2E、环境与工作流使用可直接复制的具体命令必须包含确切的包名与路径记录边界条件例如 Python 集成需要 Python 3.11、openapi-parser 需要 NODE_OPTIONS 这类容易踩坑的细节保持最小化只保留 Agent 快速运行与测试所需的内容标注依赖关系如果某一步依赖前置步骤如 package 测试依赖 test-servers必须明确写出先后关系。常见问题速查现象排查方向pnpm dev启动后找不到本地包先执行pnpm build:packages再启动 dev server单测挂在与网络/端口相关的用例先pnpm script run test-servers并pnpm script wait -p 5051 5052Playwright 本地运行失败确认PW_TEST_CONNECT_WS_ENDPOINTws://127.0.0.1:5001/已注入浏览器服务可用Python 集成测试失败确认本机 Python 版本为 3.11并在集成目录内执行python run_tests.pyopenapi-parser测试 OOM设置NODE_OPTIONS--max_old_space_size8192后重跑【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考