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/FastGPTFastGPT 是一个基于 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仓库当前锁定pnpm10.33.4必须使用 pnpm 作为包管理器仓库通过 pnpm-workspace.yaml 声明 workspace切勿混用 npm/yarn。pnpm-workspace.yaml 定义了完整的 workspace 成员这也是后续各类命令--filter、turbo run、FASTGPT_TEST_SCOPE作用范围的依据类别成员应用项目projects/app主应用、projects/code-sandbox代码沙箱、projects/marketplace、projects/mcp_server、projects/volume-manager库代码packages/*global / service / web / dal / next其他sdk/*、document/、scripts/icon及商业版pro/*模块首次初始化环境可参考 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.jsoncd projects/app pnpm dev # 启动 NextJS 开发服务器 cd projects/app pnpm build # 构建 NextJS 应用 cd projects/app pnpm start # 启动生产服务器三个命令的实际定义如下其中隐藏着一个关键前置步骤devpnpm run build:workers next devbuildpnpm run build:workers next build --debugstartnext startWorker 预编译dev/build 的第一步build:workers调用tsx scripts/build-workers.ts脚本见 projects/app/scripts/build-workers.ts其职责是扫描源目录遍历packages/service/worker下所有含index.ts的子目录如文档解析、图片处理等 workeresbuild 打包以bundle: true、platform: node、format: cjs配置将每个 worker 编译到projects/app/worker/*.js生产环境NODE_ENVproduction还会通过drop移除console/debugger复制运行时依赖将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 的浏览器兼容目标。此外该子项目还提供analyzenext experimental-analyze配合next/bundle-analyzer分析打包体积与typechecktsc --noEmit --pretty等辅助脚本。三、代码沙箱projects/code-sandbox的开发与测试代码沙箱是 FastGPT 中负责安全执行用户代码的独立服务位于projects/code-sandbox/其脚本见 projects/code-sandbox/package.jsoncd 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 可以看到完整的构建流水线清理dist产物按环境变量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通过pnpm exec tsdown打包入口tsdown.config.ts产出index.js、worker.js、python-isolated-runner.js三个 bundle所有 npm 依赖打入包内noExternal仅保留 Node 内置模块外部化复制 Python bootstrap 运行时文件并输出各产物体积统计。test即vitest run测试用例位于projects/code-sandbox/test/目录可通过pnpm test:watchvitest进入监听模式适合测试驱动开发。四、MCP 服务器projects/mcp_server的 Bun 工具链MCP 服务器实现 Model Context Protocol位于projects/mcp_server/其脚本全部基于 Bun见 projects/mcp_server/package.jsoncd projects/mcp_server bun dev # 使用 Bun 以监视模式启动 cd projects/mcp_server bun build # 构建 MCP 服务器 cd projects/mcp_server bun start # 启动 MCP 服务器各脚本的实际定义devbun --watch src/index.ts监听模式下启动入口为src/index.tsbuildbun build src/index.ts --outdirdist --targetnode chmod x dist/index.js以 Node 为目标平台产出dist/index.js并赋予可执行权限startbun src/index.ts直接以 Bun 运行时启动mcp_testnpx modelcontextprotocol/inspector调用官方 MCP Inspector 进行调试是验证 MCP 工具声明与调用是否符合协议规范的重要辅助命令。该模块依赖modelcontextprotocol/sdkcatalog 版本 ^1源码见projects/mcp_server/src/可作为自行扩展 MCP 工具的参考起点。五、工具命令lint、测试与资源生成根目录 package.json 集中定义了跨 workspace 的工具命令适用于整个仓库。pnpm lint统一代码规范lintturbo 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 typereact-hooks/rules-of-hooks关闭全局忽略node_modules/、dist/、.next/、deploy/、document/等目录。pnpm test可编排的测试运行器testnode ./scripts/test/run.mjs核心逻辑全部集中在 scripts/test/run.mjs。文档 .agents/code/commands.md 描述的命令均可在该文件中找到精确实现pnpm test # 顺序运行所有 workspace 单元测试再运行仓库根目录测试 pnpm test file-path... # 顺序运行指定测试关闭覆盖率、限制单 worker FASTGPT_TEST_SCOPEapp pnpm test # 只运行指定 workspace FASTGPT_TEST_MODEintegration pnpm test # 运行 service 集成测试 FASTGPT_TEST_MODEsandbox pnpm test # 运行沙箱集成测试 FASTGPT_TEST_MODEall pnpm test # workspace 单测 service 集成测试resolveTestPlan函数是运行器的核心它把模式 范围 路径解析为顺序执行的命令计划FASTGPT_TEST_SCOPE单测范围支持all、workspace、repo以及具体 workspace 名。workspaceFilters映射表定义了 5 个可过滤目标appfastgpt/app、adminfastgpt/admin、globalfastgpt/global、servicefastgpt/service、webfastgpt/web支持逗号分隔多个 scope如FASTGPT_TEST_SCOPEglobal,service。其中all展开为全部 workspace repo仓库根测试且不能与其他 scope 混用FASTGPT_TEST_MODE测试模式合法值为unit默认、integration、sandbox、all。integration模式目前仅支持FASTGPT_TEST_SCOPEservice内部通过turbo run test:integration --filterfastgpt/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 --concurrency1顺序执行每个命令的退出码都会被严格校验。仓库 AGENTS.md 对测试范围给出的建议是默认只测试本次改动及可能受影响的代码按依赖关系选择最小充分范围不主动运行全量测试——这与FASTGPT_TEST_SCOPE、文件路径参数的设计目标完全一致。pnpm initIcon初始化图标资源initIconnode ./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-typingschakra-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_SCOPEservice pnpm test # 4. 交付前运行 lint 与完整测试 pnpm lint pnpm test亦可使用make dev nameapp、make build nameapp imageimage等 Make 封装见 Makefile 与 dev.md其中make build的proxytaobao参数可在构建 Docker 镜像时指定淘宝代理源。七、常见问题排查修改 worker 源码后行为未更新projects/app的dev只会执行一次build:workers开发中请改用pnpm run build:workers:watch保持 worker 热编译见 projects/app/package.json测试提示Unsupported FASTGPT_TEST_SCOPEscope 只接受all、workspace、repo、app、admin、global、service、web且all不能与其他值混用校验逻辑见 scripts/test/run.mjs 的parseUnitScopesFASTGPT_TEST_MODEintegration报错集成测试模式目前仅绑定servicescope传入其他 scope 会被拒绝沙箱模式则完全不允许 scope 参数测试命令与文件路径冲突pnpm test file-path...是独立用法同时设置FASTGPT_TEST_MODE/FASTGPT_TEST_SCOPE会导致运行器抛错二者不可混用。以上所有命令均以当前仓库源码为唯一事实依据脚本定义见各 package.json测试编排逻辑见 scripts/test/run.mjsWorker 编译见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考