前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载本文系统讲解 Farm 开发服务器Dev Server的完整配置体系server下各选项端口、HTTPS、代理、HMR、CORS、中间件、HTML 回退等的用法与默认值以及server.preview预览服务器的配置方式并结合farmfe/core中 Server 类的实现源码剖析端口冲突处理、HMR WebSocket 升级握手、proxy 匹配规则和中间件挂载顺序等底层机制帮助你在开发环境与预览环境中精确控制 Farm 服务端的每一个行为。Dev Server 选项总览serverFarm 的 Dev Server 通过farm.config.ts中defineConfig的server字段进行配置所有开发服务器选项都集中在此字段下import { defineConfig } from farmfe/core; export default defineConfig({ // All dev server options are under server server: { port: 9000, //... }, });server的完整类型为UserServerConfig定义在 types.tsexport interface UserServerConfig { headers?: OutgoingHttpHeaders | undefined; port?: number; https?: HttpsServerOptions; origin?: string; allowedHosts?: string[]; hmr?: boolean | HmrOptions; proxy?: Recordstring, ProxyOptions; strictPort?: boolean; open?: boolean; host?: string | boolean; cors?: boolean | any; appType?: spa | mpa | custom; middlewares?: DevServerMiddleware[]; middlewareMode?: boolean; writeToDisk?: boolean; preview?: UserPreviewServerConfig; }各选项的默认值集中定义在 constants.ts 的DEFAULT_DEV_SERVER_OPTIONS中其中port还支持通过环境变量FARM_DEFAULT_SERVER_PORT覆盖默认回落到9000。port默认值9000也可由环境变量FARM_DEFAULT_SERVER_PORT覆盖Dev Server 监听的端口。当端口被占用时Farm 默认会自动向后尝试递增的可用端口例如9000被占用则尝试9001。从源码 http.ts 的httpServerStart可以看到捕获到EADDRINUSE错误后若未开启strictPort会打印Port xxx is in use, trying another one...并执行httpServer.listen(port, host)重试一旦实际监听的端口确定Server.listen会通过syncServerPort见 index.ts同步更新配置中的端口并在 HMR 端口与服务器端口一致时自动同步 HMR 端口及FARM_HMR_PORT编译定义保证 HMR 客户端始终连到正确的端口。strictPort默认值false是否严格使用指定端口。当端口冲突且strictPort为true时Farm 会直接抛出Port xxx is already in use错误而不是自动换端口适合 CI 或端口需固定的部署场景。host默认值localhostDev Server 监听的 host 地址。支持string或booleantrue时监听所有地址。https默认值undefined启用 TLS HTTP2。取值是传给 Node.jshttp2.createSecureServer的 options即标准的HttpsServerOptionskey、cert、ca、pfx等文件路径会被 http.ts 中的resolveHttpsConfig读取为文件内容后传入。注意启用https时必须提供有效的证书。从 http.ts 的resolveHttpServer源码可以看到一个细节如果配置了proxyFarm 使用node:https创建 HTTPS 服务器因为http-proxy尚不完全支持 http2 代理否则使用node:http2的createSecureServer并同时开启allowHTTP1: true以兼容 HTTP/1.1 客户端。headers默认值undefined为 Dev Server 的所有 HTTP 响应设置全局响应头import { defineConfig } from farmfe/core export default defineConfig({ server: { headers: { Accept: xxxx } } })cors默认值false是否开启 CORS跨域资源共享。传true时等价于传入空的 CORS 配置对象也可以传入详细的CorsOptionsorigin、methods、allowedHeaders、exposedHeaders、credentials、maxAge等类型定义见 http.ts最终由cors中间件处理。在 index.ts 的中间件初始化中cors为真值时才会挂载 CORS 中间件。appType默认值spa配置应用类型决定 Dev Server 的 HTML 回退fallback路由行为spa单页应用。未匹配的请求路由会回退到index.html。mpa多页应用。服务器会为每个路由查找对应的 HTML 文件。custom禁用自动 HTML 回退。当你有自定义的服务端路由逻辑时可用。从 htmlFallback.ts 的源码可以看出具体匹配逻辑先处理以.html结尾的路径直接取对应资源再处理根路径返回index.html其余路径先尝试pathname .html即 MPA 行为若仍未命中且appType spa最后再回退到index.html。也就是说 SPA 与 MPA 的差异只在这一步兜底与否。另外只有 GET/HEAD 请求且Accept头包含text/html或*/*时才会进入回退逻辑避免把资源请求错误地回退成 HTML。hmr默认值start命令下为true其他命令下为false开启 HMRHot Module Replacement热模块替换后Farm 会监视参与编译过程的模块变更模块变化时自动触发增量重编译并通过 WebSocket 把更新结果推送到 Farm Runtime 进行局部刷新。hmr也可以传对象进行更细粒度的配置import { defineConfig } from farmfe/core; export default defineConfig({ // All dev server options are under server server: { hmr: { // Configure the port for web socket listening port: 9802, // Configure the host for web socket listening host: localhost, // The path for the HMR endpoint path: /__hmr, } //... } });各子项的默认值定义在 constants.ts 的DEFAULT_HMR_OPTIONS中hmr.port默认值undefined回落到环境变量FARM_DEFAULT_HMR_PORT再回落到 Dev Server 端口WebSocket 服务器监听的端口。当它未单独指定或与server.port相同时HMR 直接复用 Dev Server 的 HTTP 连接升级通道当指定了不同端口时Farm 会另起一个专用的 HTTP/HTTPS 小服务器来承载 WebSocket见 ws.ts 的createWebSocketServer。若该端口被占用会抛出提示Please set a different port using the server.hmr.port option的错误。hmr.host默认值localhostWebSocket 服务器监听的 host。hmr.clientPort默认值9000HMR 客户端连接的端口号。当 Dev Server 前面有一层反向代理浏览器实际访问的端口与服务器监听端口不同时通过它告诉页面里的 HMR 客户端连接哪个端口。hmr.path默认值/__hmrHMR WebSocket 端点的 URL 路径。实际生效路径会与publicPath拼接ws.ts 中path.posix.join(hmrBase, hmrPath)。hmr.timeout默认值0HMR WebSocket 连接的超时时间毫秒。hmr.overlay默认值true当 HMR 更新发生错误时是否在浏览器中显示错误遮罩层。hmr.protocol默认值自动检测HMR 连接使用的 WebSocket 协议例如ws或wss。除了服务端监听配置源码中还能看到 HMR 的握手细节在 ws.ts 中Farm 通过监听 HTTPupgrade事件处理 WebSocket 升级请求并要求请求头sec-websocket-protocol为farm_hmr、请求路径精确匹配 HMR 端点、Origin位于允许的 HMR origins 或server.allowedHosts之中三者同时满足才会完成握手——这是一层针对 HMR 通道的安全校验。文件变化触发的更新链路则位于 index.tsWatcher捕获add/unlink/change事件后交给HmrEngine.hmrUpdate执行增量编译再经 WebSocket 广播给所有客户端。proxy默认值undefined配置开发服务器代理。Farm 基于http-proxy实现代理proxy.ts各选项与 http-proxy 的文档一致例如import { defineConfig } from farmfe/core; export default defineConfig({ server: { proxy: { /api: { target: https://music-erkelost.vercel.app/banner, changeOrigin: true, pathRewrite: (path: any) path.replace(/^\/api/, ), }, }, }, });结合源码proxy.ts还有几点值得了解代理上下文既支持前缀也支持正则doesProxyContextMatchUrl判断规则为——以^开头的 key 按正则匹配否则按 URL 前缀匹配。仓库示例 examples/server-proxy/farm.config.ts 就使用了正则写法server: { proxy: { ^/api: { target: http://localhost:3000, changeOrigin: true, } } }bypass支持动态放行返回string表示改写req.url后走后续中间件返回false表示直接 404。WebSocket 代理当ws: true或target以ws:/wss:开头时Farm 会监听 HTTPupgrade事件并通过proxy.ws转发 WebSocket 连接rewriteWsOrigin可在代理 WebSocket 时把Origin头改写为目标地址规避某些 WebSocket 服务的 Origin 校验。代理配置为字符串时的简写形式等价于{ target: ..., changeOrigin: true }。proxy的挂载位置在 CORS 之后、静态/资源中间件之前见 index.ts因此代理请求优先于本地资源匹配。open默认值false编译完成后自动用默认浏览器打开对应页面。实现位于 index.ts取resolvedUrls中本地地址或网络地址的第一个 URL 调用openBrowser打开。middlewares默认值[]为 Dev Server 配置自定义中间件数组。每个中间件是一个接收Server实例、返回 connect 兼容中间件函数的函数import { defineConfig } from farmfe/core; export default defineConfig({ server: { middlewares: [ (server) { return (req, res, next) { // custom middleware logic next(); }; }, ], }, });从 index.ts 可以看到用户中间件在所有内置中间件CORS、proxy、静态资源、资源服务、configureServer插件钩子返回的中间件等之后、HTML fallback 之前执行适合做请求日志、鉴权拦截或自定义 API 路由。middlewareMode默认值false是否以中间件模式运行。为true时Dev Server 不再启动自己的 HTTP 服务器index.ts 中middlewareMode为真时httpServer保持null便于把 Farm 的编译与资源服务能力集成进已有的服务端框架。此模式下不会打印服务器 URL也不会注册SIGTERM监听。origin默认值服务器的 origin 地址用于在响应中配置 Dev Server 的源地址。注意 index.ts 中的处理若origin以/结尾Farm 会主动去掉尾部斜杠并打印告警server.origin should not end with /。allowedHosts默认值[]Dev Server 允许的主机名列表。配置后仅请求Host头匹配列表中条目的请求会被服务该列表同时被用于 HMR WebSocket 升级时的 Origin 白名单校验见 ws.ts。writeToDisk默认值false默认情况下编译产物保存在内存中并直接在内存里被服务。将writeToDisk设为true后Farm 会把开发资源落盘到磁盘。在 index.ts 中该选项决定了资源服务中间件的选择true时使用resourceDiskMiddleware从磁盘读取否则使用resourceMiddleware从内存读取编译完成后也相应地调用compiler.writeResourcesToDisk()或compiler.callWriteResourcesHook()。请求处理链路从源码看内置中间件顺序把 index.ts 的#initializeMiddlewares串起来Dev Server 的 connect 中间件链顺序为hmrPingMiddleware—— HMR 心跳CORS 中间件cors开启时proxyMiddlewareproxy配置时publicPathMiddlewarepublicPath ! /时publicMiddlewarepublicDir存在时处理 public 静态目录lazyCompilationMiddleware开启懒编译时staticMiddleware—— 静态资源outputFilesMiddleware—— 通过_output_files检查 dev 资源树资源服务中间件resourceDiskMiddleware或resourceMiddleware取决于writeToDiskconfigureServer插件钩子返回的中间件用户配置的server.middlewareshtmlFallbackMiddlewarenotFoundMiddlewareappType为spa/mpa时。这个顺序解释了前文各选项的行为优先级代理先于本地资源匹配用户中间件先于 HTML 回退appType: custom之所以能禁用自动回退正是因为第 12 步的htmlFallbackMiddleware不会被挂载。Preview Server 选项server.preview预览服务器用于farm preview命令专门静态服务构建产物。预览相关选项嵌套在server.preview下类型为UserPreviewServerConfigexport interface UserPreviewServerConfig { headers?: OutgoingHttpHeaders | false | undefined; host?: string | boolean; port?: number; strictPort?: boolean; https?: SecureServerOptions; distDir?: string; open?: boolean | string; cors?: boolean | any; proxy?: Recordstring, ProxyOptions; middlewares?: PreviewServerMiddleware[]; }实现位于 preview.ts其PreviewServer类复用与 Dev Server 相同的httpServer基类端口冲突处理、strictPort、HTTPS 解析逻辑一致并额外挂载compression压缩中间件与基于sirv的静态资源服务。preview.port默认值1911也可由环境变量FARM_DEFAULT_SERVER_PORT覆盖见 constants.ts预览服务器监听的端口。preview.host默认值localhost预览服务器运行的 host。preview.strictPort默认值false是否严格使用指定端口。端口被占用且此项为true时抛出错误。preview.distDir默认值dist指定构建产物输出目录的位置。若未指定Farm 会从compilation.output.path解析相对路径基于root解析。preview.open默认值false是否自动在默认浏览器中打开预览服务器。preview.https默认值继承自server.https预览服务器的安全服务器选项设为false可关闭预览的 HTTPS。preview.headers默认值继承自server.headers预览服务器每个响应携带的 HTTP 头设为false可禁用。preview.proxy默认值继承自server.proxy预览服务器的代理选项与server.proxy使用同一套ProxyOptions实现设为false可禁用代理。preview.middlewares默认值[]预览服务器中间件用法与server.middlewares相同。从 preview.ts 可以看到其挂载顺序为CORS → proxy → compression → publicPath → sirv 静态服务 → 用户中间件 →notFoundMiddlewareappType为spa/mpa时其中appType直接读取自server.appType。小结Farm Dev Server 的全部开发期服务行为集中在server字段下默认端口9000strictPort、host、https、open等控制网络层hmr支持布尔开关与对象细配WebSocket 端点默认/__hmr端口与server.port相同时会自动同步proxy基于http-proxy支持前缀/正则上下文、bypass、rewrite与 WebSocket 代理appType决定 HTML 回退策略middlewares与middlewareMode提供自定义与嵌入式集成能力writeToDisk控制资源内存服务或落盘farm preview使用server.preview静态服务构建产物多数选项可继承server下的同名配置便于预览与开发环境保持一致。以上行为均可在packages/core/src/server/与packages/core/src/config/constants.ts中直接查证配置时以当前仓库farmfe/core的实际类型定义为准。赞分享前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载相关推荐Phoenix Docker 开发环境中的 Vite Dev Server端口、路径前缀与 HMR 全链路解析Phoenix Docker 开发环境中的 Vite Dev Server端口、路径前缀与 HMR 全链路解析 导读 本文围绕 Phoenix 仓库内 scr可观测性AI 评测LLMOpsAI 应用人工智能webpack-dev-server 的 hot 配置详解HMR 热更新true / false / only实战指南webpack dev server 的 hot 配置详解HMR 热更新true / false / only实战指南 导读 hot 是 webpac开发工具后端webpack-dev-server终极配置指南20个实用选项详解webpack dev server终极配置指南20个实用选项详解 webpack dev server是webpack官方推出的开发服务器为前端开发者提供开发工具后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考