FastGPT 开发命令全指南：基于 pnpm Workspace 的 Monorepo 本地开发、构建与测试实践

FastGPT 开发命令全指南：基于 pnpm Workspace 的 Monorepo 本地开发、构建与测试实践

【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT

FastGPT 是一个基于 LLM 的知识库平台，提供数据处理、RAG 检索与可视化 AI 工作流编排能力，其代码仓库采用 pnpm Workspace 管理的 TypeScript Monorepo 结构。本文以仓库文档 .agents/code/commands.md 为骨架，结合 package.json 及各子项目源码中的真实脚本实现，系统讲解主应用、代码沙箱、MCP 服务器的启动/构建命令，以及 lint、测试、图标与主题类型生成等工具命令，帮助你在本地快速搭建开发环境并精确掌控测试范围。

一、环境准备与前置条件

在执行任何开发命令前，需要先确认仓库根目录的工程配置。根目录 package.json 的engines与packageManager字段明确限定了运行时环境：

• Node.js >= 22.23.2：所有子项目的engines.node均为该版本，是运行 Next.js 16、Vitest 4 等工具链的最低要求；
• pnpm 10.x（仓库当前锁定pnpm@10.33.4）：必须使用 pnpm 作为包管理器，仓库通过 pnpm-workspace.yaml 声明 workspace，切勿混用 npm/yarn。

pnpm-workspace.yaml 定义了完整的 workspace 成员，这也是后续各类命令（--filter、turbo run、FASTGPT_TEST_SCOPE）作用范围的依据：

首次初始化环境可参考 dev.md：

# 在仓库根目录执行 pnpm i # 若 postinstall 未自动触发，可手动构建 SDK 依赖 pnpm build:sdks

根目录postinstall脚本会依次执行pnpm gen:theme-typings与pnpm run build:sdks（见 package.json），因此安装依赖后基础构建产物通常已就绪。后续所有命令默认都应在仓库根目录执行，文档 .agents/code/commands.md 对此有明确说明。

二、主应用（projects/app）的启动与构建

FastGPT 主应用位于projects/app/，是一个基于 Next.js 的全栈应用（前端页面 + API 路由），其脚本定义见 projects/app/package.json：

cd projects/app && pnpm dev # 启动 NextJS 开发服务器 cd projects/app && pnpm build # 构建 NextJS 应用 cd projects/app && pnpm start # 启动生产服务器

三个命令的实际定义如下，其中隐藏着一个关键前置步骤：

• dev=pnpm run build:workers && next dev
• build=pnpm run build:workers && next build --debug
• start=next start

Worker 预编译：dev/build 的第一步

build:workers调用tsx scripts/build-workers.ts（脚本见 projects/app/scripts/build-workers.ts），其职责是：

1. 扫描源目录：遍历packages/service/worker下所有含index.ts的子目录（如文档解析、图片处理等 worker）；
2. esbuild 打包：以bundle: true、platform: 'node'、format: 'cjs'配置将每个 worker 编译到projects/app/worker/*.js，生产环境（NODE_ENV=production）还会通过drop移除console/debugger；
3. 复制运行时依赖：将@llamaindex/liteparse-wasm、@fastgpt-sdk/anydoc、jschardet等 worker 运行时包复制到 worker 目录旁的node_modules，保证 WASM 等资源可被 worker 线程就近加载。

该脚本同时支持--watch模式（pnpm run build:workers:watch），在开发阶段可保持 worker 热重载，避免每次修改 worker 源文件后手动重新编译。理解这一点有助于排查"改了packages/service/worker却不起效"的问题——需要重新触发build:workers。

生产构建与启动

pnpm build使用next build --debug输出详细构建日志，可用于定位页面与路由的构建瓶颈；构建完成后，pnpm start通过next start以生产模式提供服务。projects/app/package.json的browserslist声明了 Chrome >= 80、Edge >= 80、Firefox >= 74、Safari >= 13 的浏览器兼容目标。

此外该子项目还提供analyze（next experimental-analyze，配合@next/bundle-analyzer分析打包体积）与typecheck（tsc --noEmit --pretty）等辅助脚本。

三、代码沙箱（projects/code-sandbox）的开发与测试

代码沙箱是 FastGPT 中负责安全执行用户代码的独立服务，位于projects/code-sandbox/，其脚本见 projects/code-sandbox/package.json：

cd projects/code-sandbox && pnpm dev # 以监视模式启动 cd projects/code-sandbox && pnpm build # 构建沙箱服务 cd projects/code-sandbox && pnpm test # 运行 Vitest 测试

需要说明的是：文档 .agents/code/commands.md 中描述该模块"以监视模式启动（Bun）"，而当前仓库实际实现中，dev脚本已演进为tsx watch src/index.ts（基于 Node + Hono 的统一子进程模型，见 projects/code-sandbox/package.json 的 description 字段）；Bun 目前主要用于 MCP 服务器模块（见下一节）。以仓库源码为准，dev会通过tsx watch监听src/index.ts及其依赖，代码变更后自动重启服务，适合沙箱逻辑的迭代调试。

build命令对应sh build.sh，从 projects/code-sandbox/build.sh 可以看到完整的构建流水线：

1. 清理dist产物；
2. 按环境变量SANDBOX_BUILD_NATIVE_PYTHON/SANDBOX_BUILD_NATIVE_JS决定是否编译 Python 沙箱库（Go 构建fastgpt_python_sandbox.so）与 JS 沙箱原生扩展（GCC 构建fastgpt_js_sandbox.node，脚本见 projects/code-sandbox/package.json 中的build:native:python/build:native:js）；
3. 通过pnpm exec tsdown打包入口（tsdown.config.ts），产出index.js、worker.js、python-isolated-runner.js三个 bundle，所有 npm 依赖打入包内（noExternal），仅保留 Node 内置模块外部化；
4. 复制 Python bootstrap 运行时文件，并输出各产物体积统计。

test即vitest run，测试用例位于projects/code-sandbox/test/目录，可通过pnpm test:watch（vitest）进入监听模式，适合测试驱动开发。

四、MCP 服务器（projects/mcp_server）的 Bun 工具链

MCP 服务器实现 Model Context Protocol，位于projects/mcp_server/，其脚本全部基于 Bun，见 projects/mcp_server/package.json：

cd projects/mcp_server && bun dev # 使用 Bun 以监视模式启动 cd projects/mcp_server && bun build # 构建 MCP 服务器 cd projects/mcp_server && bun start # 启动 MCP 服务器

各脚本的实际定义：

• dev=bun --watch src/index.ts：监听模式下启动，入口为src/index.ts；
• build=bun build src/index.ts --outdir=dist --target=node && chmod +x dist/index.js：以 Node 为目标平台产出dist/index.js并赋予可执行权限；
• start=bun src/index.ts：直接以 Bun 运行时启动；
• mcp_test=npx @modelcontextprotocol/inspector：调用官方 MCP Inspector 进行调试，是验证 MCP 工具声明与调用是否符合协议规范的重要辅助命令。

该模块依赖@modelcontextprotocol/sdk（catalog 版本 ^1），源码见projects/mcp_server/src/，可作为自行扩展 MCP 工具的参考起点。

五、工具命令：lint、测试与资源生成

根目录 package.json 集中定义了跨 workspace 的工具命令，适用于整个仓库。

pnpm lint：统一代码规范

lint=turbo run lint，通过 Turborepo 并行执行各子项目的 ESLint。主应用projects/app的lint为eslint ./src；根级 ESLint 配置见 eslint.config.mjs，它基于eslint-config-next/core-web-vitals与typescript-eslint，并将projects/app/、pro/admin/设为 Next.js 根目录。值得注意的规则包括：

• @typescript-eslint/no-explicit-any关闭（允许显式any）；
• 强制consistent-type-imports（类型必须使用import type）；
• react-hooks/rules-of-hooks关闭；
• 全局忽略node_modules/、dist/、.next/、deploy/、document/等目录。

pnpm test：可编排的测试运行器

test=node ./scripts/test/run.mjs，核心逻辑全部集中在 scripts/test/run.mjs。文档 .agents/code/commands.md 描述的命令均可在该文件中找到精确实现：

pnpm test # 顺序运行所有 workspace 单元测试，再运行仓库根目录测试 pnpm test <file-path...> # 顺序运行指定测试，关闭覆盖率、限制单 worker FASTGPT_TEST_SCOPE=app pnpm test # 只运行指定 workspace FASTGPT_TEST_MODE=integration pnpm test # 运行 service 集成测试 FASTGPT_TEST_MODE=sandbox pnpm test # 运行沙箱集成测试 FASTGPT_TEST_MODE=all pnpm test # workspace 单测 + service 集成测试

resolveTestPlan函数是运行器的核心，它把"模式 + 范围 + 路径"解析为顺序执行的命令计划：

• FASTGPT_TEST_SCOPE（单测范围）：支持all、workspace、repo以及具体 workspace 名。workspaceFilters映射表定义了 5 个可过滤目标：app（@fastgpt/app）、admin（@fastgpt/admin）、global（@fastgpt/global）、service（@fastgpt/service）、web（@fastgpt/web）；支持逗号分隔多个 scope（如FASTGPT_TEST_SCOPE=global,service）。其中all展开为全部 workspace +repo（仓库根测试），且不能与其他 scope 混用；
• FASTGPT_TEST_MODE（测试模式）：合法值为unit（默认）、integration、sandbox、all。integration模式目前仅支持FASTGPT_TEST_SCOPE=service，内部通过turbo run test:integration --filter=@fastgpt/service执行；sandbox模式不接受 scope，通过pnpm --dir packages/service test:integration:sandbox运行；all模式同样不接受 scope，语义为"workspace 单测完成后再跑 service 集成测试"；
• 指定文件路径：当传入<file-path...>参数时，运行器改调node ./scripts/test/light.mjs <paths>（见 scripts/test/light.mjs），以关闭覆盖率、单 worker 的轻量模式顺序运行局部测试，避免多个 Vitest/Mongo 实例争抢本地资源；该用法不能与FASTGPT_TEST_MODE/FASTGPT_TEST_SCOPE组合，否则会直接抛错；
• 执行细节：workspace 单测通过withMongo.mjs包裹（scripts/test/withMongo.mjs，提供内存 Mongo 环境），再以turbo run test --concurrency=1顺序执行，每个命令的退出码都会被严格校验。

仓库 AGENTS.md 对测试范围给出的建议是：默认只测试本次改动及可能受影响的代码，按依赖关系选择最小充分范围，不主动运行全量测试——这与FASTGPT_TEST_SCOPE、文件路径参数的设计目标完全一致。

pnpm initIcon：初始化图标资源

initIcon=node ./scripts/icon/init.js && prettier ... --write "packages/web/components/common/Icon/constants.ts"。从 scripts/icon/init.js 的实现看，它会递归扫描packages/web/components/common/Icon/icons下所有.svg与.tsx文件，生成懒加载映射写入constants.ts的iconPaths对象。当你新增图标文件后执行该命令，即可让新的图标被统一注册；scripts/icon/index.js对应的pnpm previewIcon则用于预览图标效果。

pnpm gen:theme-typings：生成 Chakra UI 主题类型

gen:theme-typings=chakra-cli tokens packages/web/styles/theme.ts --out node_modules/.pnpm/node_modules/@chakra-ui/styled-system/dist/theming.types.d.ts。它基于packages/web/styles/theme.ts中的主题 token 定义，生成强类型的 Chakra UI 主题类型声明，使 IDE 在组件中使用theme.colors.*等属性时获得类型提示与校验。该命令在postinstall阶段会自动执行，手动改动主题文件后也可再次运行刷新类型。

六、常用开发工作流小结

结合 dev.md 与上述命令，推荐的工作流如下：

# 1. 仓库根目录安装依赖（自动触发 theme-typings 与 SDK 构建） pnpm i # 2. 启动主应用开发服务器（自动预编译 worker） cd projects/app && pnpm dev # 3. 仅验证本次改动：指定文件或最小 workspace 范围 pnpm test projects/app/src/pages/api/xxx.test.ts FASTGPT_TEST_SCOPE=service pnpm test # 4. 交付前运行 lint 与完整测试 pnpm lint pnpm test

亦可使用make dev name=app、make build name=app image=<image>等 Make 封装（见 Makefile 与 dev.md），其中make build的proxy=taobao参数可在构建 Docker 镜像时指定淘宝代理源。

七、常见问题排查

• 修改 worker 源码后行为未更新：projects/app的dev只会执行一次build:workers，开发中请改用pnpm run build:workers:watch保持 worker 热编译（见 projects/app/package.json）；
• 测试提示Unsupported FASTGPT_TEST_SCOPE：scope 只接受all、workspace、repo、app、admin、global、service、web，且all不能与其他值混用（校验逻辑见 scripts/test/run.mjs 的parseUnitScopes）；
• FASTGPT_TEST_MODE=integration报错：集成测试模式目前仅绑定servicescope，传入其他 scope 会被拒绝；沙箱模式则完全不允许 scope 参数；
• 测试命令与文件路径冲突：pnpm test <file-path...>是独立用法，同时设置FASTGPT_TEST_MODE/FASTGPT_TEST_SCOPE会导致运行器抛错，二者不可混用。

以上所有命令均以当前仓库源码为唯一事实依据：脚本定义见各 package.json，测试编排逻辑见 scripts/test/run.mjs，Worker 编译见 projects/app/scripts/build-workers.ts，沙箱构建见 projects/code-sandbox/build.sh。若你使用商业版模块（pro/*），部分 scope 与命令需要对应模块就位后方可运行。

【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT