Ambidex settings配置清单HOST、FILESYSTEM_PATHS等12个关键设置项详解【免费下载链接】ambidexEffortlessly host your React app on both the client and the server. Some call it isomorphic JavaScript - we call it Ambidex.项目地址: https://gitcode.com/gh_mirrors/am/ambidexAmbidex 是一个轻量级的同构 React 框架isomorphic JavaScript让同一个 React 应用既能跑在浏览器里也能跑在服务器上。它的所有行为几乎都由一个settings配置对象决定——这篇Ambidex settings 配置清单将逐条详解 HOST、PORT、FILESYSTEM_PATHS 等 12 个关键设置项帮助新手一次性配对自己的应用少踩坑。为什么需要一份配置清单Ambidex 的理念很简单服务器渲染首屏利于 SEO 和首屏速度客户端接管后续交互响应快、省带宽。它用 mixin 抹平了两种环境的差异你只需编写一次应用逻辑。而这一切的起点就是一个配置字典new Ambidex({ settings: require(./settings.local.js), middlewareInjector: function (stack) { /* 在这里注入你的 Mach 中间件 */ } });构造函数返回一个 Promise应用开始正常服务时才 resolve见 src/Ambidex.server.js 第 42-98 行。如果忘了传 settings它会直接抛出明确的报错提示所以下面这 12 个字段就是你要写全的清单。12 个 Ambidex settings 设置项总览#设置项必填一句话作用1NAME建议日志中显示的应用名称2SHORT_NAME可选top等进程监控中显示的进程名3HOST必填应用对外提供的域名/主机名4PORT必填浏览器地址栏里的端口5VM_PORT可选负载均衡器背后实际监听的端口6BASE_URL可选挂在 TardisGallery 下的子路径7WEBPACK_PORTHMR 时必填Webpack Dev Server 的端口8ENABLE_HOT_MODULE_REPLACEMENT可选是否开启热更新9TITLE_SEPARATOR可选各 section 标题之间的分隔符10FAV_ICON_URL建议favicon 的 301 重定向目标11FILESYSTEM_PATHS必填关键文件的位置ROUTES/STYLES/BUNDLES 等12SERVER_ONLY_MODULE_NAMES可选告诉 Webpack 忽略的纯服务端模块下面按功能分组逐一展开。身份标识NAME 与 SHORT_NAMENAME日志里对应用的称呼例如My Awesome App。Ambidex 启动时会打印Starting mach for ${NAME} on ${HOST}:${port}…所以起个辨识度高的名字排错时很舒服。SHORT_NAME可选不含空格和大写的变体例如my_awesome_app。设置后会被写入process.titlesrc/Ambidex.server.js 第 75-76 行在top、ps等工具里一眼就能认出自己的进程。网络配置HOST、PORT、VM_PORT、BASE_URL、WEBPACK_PORT这 5 项决定了用户怎么访问到你的应用。HOST 与 PORT服务的基本坐标HOST是应用对外的主机名如tardis.localPORT是浏览器地址栏里的端口。_startServingStack会用mach.serve在HOST:PORT上启动服务。本地开发时官方示例应用直接配了HOST: tardis.local、PORT: 8080见 src/addons/tardis/settings.default.js。VM_PORT负载均衡器场景如果你的应用部署在负载均衡器之后把VM_PORT设为 Ambidex 真正监听的端口负载均衡器再对外暴露标准端口。源码中的取法是settings.VM_PORT || settings.PORT即不配置时自动回退到PORT。BASE_URL多版本并排展示当你的应用被挂载在一个 TardisGallery 里时用BASE_URL指定它的路由树挂载位置——比如版本 A 挂在/A/、版本 B 挂在/B/多个应用变体就能在同一台服务器上并排服务。WEBPACK_PORT热更新时的第二端口开启 HMR 后会有两个端口PORT由 Mach 提供 HTML 页面WEBPACK_PORT由 Webpack Dev Server 提供 JS/CSS bundle。Ambidex 会把 devServer 源地址设为http://HOST:WEBPACK_PORTsrc/Ambidex.server.js 第 209 行并在响应头中为它加上 CORSAccess-Control-Allow-Origin跨端口加载才不会失败。一键热更新ENABLE_HOT_MODULE_REPLACEMENT 开关这是开发体验的核心开关true与false走的是两条完全不同的构建路径设为true开发环境推荐启动 Webpack Dev Serverhot: true支持 react-hot-loader 级别的实时编辑HTML 中的style和script指向WEBPACK_PORT上的styles.js、jsx.js更妙的是Ambidex 还监听 webpack 的after-compile钩子清掉require.cache里用户代码的缓存并重新加载外部模块——服务端渲染的代码也能热更新不必每次改代码都重启服务。设为false生产环境Webpack 执行一次完整构建并压缩文件minimizeFileSize: true构建产物被内联进每个 HTML 响应省去额外的资源请求此时BUNDLES目录用作 webpack 输出的落盘位置。官方示例按环境区分NODE_ENV local时为true。页面外观TITLE_SEPARATOR 与 FAV_ICON_URLTITLE_SEPARATOR可选每个路由 handler 可以声明自己的 section title通过Ambidex.mixins.Title多个 section 标题之间会用这个字符串拼接如 - 。服务端渲染时写入title标签客户端则同步到document.title。FAV_ICON_URL设置后/favicon.ico的请求会被 301 重定向到该地址src/Ambidex.server.js 第 324-332 行方便把图标放到 CDN 上统一管理。FILESYSTEM_PATHS 详解最容易出错的必填项FILESYSTEM_PATHS告诉 Ambidex 你的关键文件都在哪。启动时_verifyPaths会把它们统一转成绝对路径并逐个校验存在性——任何一项路径不对服务会带着清晰的报错拒绝启动Make sure FILESYSTEM_PATHS[BASE] and [XXX] are set correctly。子键说明BASE路径基准其他FILESYSTEM_PATHS都相对它解析。设成__dirname即相对你的 settings 文件所在目录。ROUTES路由树的入口必填该路径的模块应导出你的根Route。服务端每次请求都会用它跑 ReactRouter。STYLES样式入口可选不配置时默认使用框架自带的 src/defaults/styles/init.css——一套对齐 React Native 默认值的 CSS所有块级元素默认 flexbox 布局、默认 Roboto 字体。想覆盖默认值把自己的 CSS 文件指过来即可。BUNDLESwebpack 输出目录必填存放生产模式下内联到 HTML 的构建产物每个 Ambidex 实例要用自己独立的 bundles 目录官方示例是__dirname /bundles/。源码会自动帮目录补上结尾的/。NUCLEAR_DEFINITIONSNuclear 状态定义可选该模块导出 actions/getters/stores 定义Ambidex 会在服务端为每个请求创建 Reactor 并注入状态内置的routerState等 store 见 src/nuclearDefinitions/。不配则不启用 Nuclear。一个标准写法参考 src/addons/tardis/settings.default.jsFILESYSTEM_PATHS: { ROUTES: ${ __dirname }/routes.jsx, STYLES: ${ __dirname }/styles.css, BUNDLES: ${ __dirname }/bundles/, }纯服务端模块SERVER_ONLY_MODULE_NAMES这是一个模块名数组如[jsdom]传给 Webpack 后会被完全忽略——用于那些只能在 Node 中运行、无法打进浏览器 bundle 的依赖src/Ambidex.server.js 第 215-216 行。如果你引入了这类包却不在这里声明构建时会报无法解析或平台不兼容的错误。附赠CUSTOM_SETTINGS 收纳你自己的配置settings本质上就是一个字典你可以往里放任何自定义值。但注意两点必须能通过 JSON 序列化——整个 settings 会被JSON.stringify后作为 webpack 常量注入客户端代码函数、循环引用之类会直接导致构建失败自定义键名建议放进settings.CUSTOM_SETTINGS下例如STATIC_URL指向你的 CDN避免未来 Ambidex 新增同名设置项时和你的配置撞车。实用技巧settings 文件的三个好习惯按环境拆分文件settings.common.js存放所有环境共享的部分settings.local.js/settings.production.js等小文件只写各自环境的差异改HOST、PORT、ENABLE_HOT_MODULE_REPLACEMENT之类。利用默认值合并官方代码用recursiveCloneWithDefaults把用户配置叠加在默认配置之上见 src/addons/utilities.js你只写差量即可不必复制整份默认设置。在组件里读配置任何 handler 混入 Settings mixin 后调用this.getAmbidexSettings()就能拿到当前完整的 settings 对象服务端还会通过loadSettingsaction 把它同步进 Nuclear store两端行为一致。小结Ambidex 的配置面不大却条条有用NAME/SHORT_NAME管身份HOST/PORT/VM_PORT/BASE_URL/WEBPACK_PORT管访问ENABLE_HOT_MODULE_REPLACEMENT管开发体验TITLE_SEPARATOR/FAV_ICON_URL管外观FILESYSTEM_PATHS管文件位置SERVER_ONLY_MODULE_NAMES管构建边界。把这份清单对照着填进你的 settings 文件服务启动日志里看到Starting mach for 你的应用 on HOST:PORT…的那一刻你的同构 React 应用就跑起来了。【免费下载链接】ambidexEffortlessly host your React app on both the client and the server. Some call it isomorphic JavaScript - we call it Ambidex.项目地址: https://gitcode.com/gh_mirrors/am/ambidex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ambidex settings配置清单：HOST、FILESYSTEM_PATHS等12个关键设置项详解
Ambidex settings配置清单HOST、FILESYSTEM_PATHS等12个关键设置项详解【免费下载链接】ambidexEffortlessly host your React app on both the client and the server. Some call it isomorphic JavaScript - we call it Ambidex.项目地址: https://gitcode.com/gh_mirrors/am/ambidexAmbidex 是一个轻量级的同构 React 框架isomorphic JavaScript让同一个 React 应用既能跑在浏览器里也能跑在服务器上。它的所有行为几乎都由一个settings配置对象决定——这篇Ambidex settings 配置清单将逐条详解 HOST、PORT、FILESYSTEM_PATHS 等 12 个关键设置项帮助新手一次性配对自己的应用少踩坑。为什么需要一份配置清单Ambidex 的理念很简单服务器渲染首屏利于 SEO 和首屏速度客户端接管后续交互响应快、省带宽。它用 mixin 抹平了两种环境的差异你只需编写一次应用逻辑。而这一切的起点就是一个配置字典new Ambidex({ settings: require(./settings.local.js), middlewareInjector: function (stack) { /* 在这里注入你的 Mach 中间件 */ } });构造函数返回一个 Promise应用开始正常服务时才 resolve见 src/Ambidex.server.js 第 42-98 行。如果忘了传 settings它会直接抛出明确的报错提示所以下面这 12 个字段就是你要写全的清单。12 个 Ambidex settings 设置项总览#设置项必填一句话作用1NAME建议日志中显示的应用名称2SHORT_NAME可选top等进程监控中显示的进程名3HOST必填应用对外提供的域名/主机名4PORT必填浏览器地址栏里的端口5VM_PORT可选负载均衡器背后实际监听的端口6BASE_URL可选挂在 TardisGallery 下的子路径7WEBPACK_PORTHMR 时必填Webpack Dev Server 的端口8ENABLE_HOT_MODULE_REPLACEMENT可选是否开启热更新9TITLE_SEPARATOR可选各 section 标题之间的分隔符10FAV_ICON_URL建议favicon 的 301 重定向目标11FILESYSTEM_PATHS必填关键文件的位置ROUTES/STYLES/BUNDLES 等12SERVER_ONLY_MODULE_NAMES可选告诉 Webpack 忽略的纯服务端模块下面按功能分组逐一展开。身份标识NAME 与 SHORT_NAMENAME日志里对应用的称呼例如My Awesome App。Ambidex 启动时会打印Starting mach for ${NAME} on ${HOST}:${port}…所以起个辨识度高的名字排错时很舒服。SHORT_NAME可选不含空格和大写的变体例如my_awesome_app。设置后会被写入process.titlesrc/Ambidex.server.js 第 75-76 行在top、ps等工具里一眼就能认出自己的进程。网络配置HOST、PORT、VM_PORT、BASE_URL、WEBPACK_PORT这 5 项决定了用户怎么访问到你的应用。HOST 与 PORT服务的基本坐标HOST是应用对外的主机名如tardis.localPORT是浏览器地址栏里的端口。_startServingStack会用mach.serve在HOST:PORT上启动服务。本地开发时官方示例应用直接配了HOST: tardis.local、PORT: 8080见 src/addons/tardis/settings.default.js。VM_PORT负载均衡器场景如果你的应用部署在负载均衡器之后把VM_PORT设为 Ambidex 真正监听的端口负载均衡器再对外暴露标准端口。源码中的取法是settings.VM_PORT || settings.PORT即不配置时自动回退到PORT。BASE_URL多版本并排展示当你的应用被挂载在一个 TardisGallery 里时用BASE_URL指定它的路由树挂载位置——比如版本 A 挂在/A/、版本 B 挂在/B/多个应用变体就能在同一台服务器上并排服务。WEBPACK_PORT热更新时的第二端口开启 HMR 后会有两个端口PORT由 Mach 提供 HTML 页面WEBPACK_PORT由 Webpack Dev Server 提供 JS/CSS bundle。Ambidex 会把 devServer 源地址设为http://HOST:WEBPACK_PORTsrc/Ambidex.server.js 第 209 行并在响应头中为它加上 CORSAccess-Control-Allow-Origin跨端口加载才不会失败。一键热更新ENABLE_HOT_MODULE_REPLACEMENT 开关这是开发体验的核心开关true与false走的是两条完全不同的构建路径设为true开发环境推荐启动 Webpack Dev Serverhot: true支持 react-hot-loader 级别的实时编辑HTML 中的style和script指向WEBPACK_PORT上的styles.js、jsx.js更妙的是Ambidex 还监听 webpack 的after-compile钩子清掉require.cache里用户代码的缓存并重新加载外部模块——服务端渲染的代码也能热更新不必每次改代码都重启服务。设为false生产环境Webpack 执行一次完整构建并压缩文件minimizeFileSize: true构建产物被内联进每个 HTML 响应省去额外的资源请求此时BUNDLES目录用作 webpack 输出的落盘位置。官方示例按环境区分NODE_ENV local时为true。页面外观TITLE_SEPARATOR 与 FAV_ICON_URLTITLE_SEPARATOR可选每个路由 handler 可以声明自己的 section title通过Ambidex.mixins.Title多个 section 标题之间会用这个字符串拼接如 - 。服务端渲染时写入title标签客户端则同步到document.title。FAV_ICON_URL设置后/favicon.ico的请求会被 301 重定向到该地址src/Ambidex.server.js 第 324-332 行方便把图标放到 CDN 上统一管理。FILESYSTEM_PATHS 详解最容易出错的必填项FILESYSTEM_PATHS告诉 Ambidex 你的关键文件都在哪。启动时_verifyPaths会把它们统一转成绝对路径并逐个校验存在性——任何一项路径不对服务会带着清晰的报错拒绝启动Make sure FILESYSTEM_PATHS[BASE] and [XXX] are set correctly。子键说明BASE路径基准其他FILESYSTEM_PATHS都相对它解析。设成__dirname即相对你的 settings 文件所在目录。ROUTES路由树的入口必填该路径的模块应导出你的根Route。服务端每次请求都会用它跑 ReactRouter。STYLES样式入口可选不配置时默认使用框架自带的 src/defaults/styles/init.css——一套对齐 React Native 默认值的 CSS所有块级元素默认 flexbox 布局、默认 Roboto 字体。想覆盖默认值把自己的 CSS 文件指过来即可。BUNDLESwebpack 输出目录必填存放生产模式下内联到 HTML 的构建产物每个 Ambidex 实例要用自己独立的 bundles 目录官方示例是__dirname /bundles/。源码会自动帮目录补上结尾的/。NUCLEAR_DEFINITIONSNuclear 状态定义可选该模块导出 actions/getters/stores 定义Ambidex 会在服务端为每个请求创建 Reactor 并注入状态内置的routerState等 store 见 src/nuclearDefinitions/。不配则不启用 Nuclear。一个标准写法参考 src/addons/tardis/settings.default.jsFILESYSTEM_PATHS: { ROUTES: ${ __dirname }/routes.jsx, STYLES: ${ __dirname }/styles.css, BUNDLES: ${ __dirname }/bundles/, }纯服务端模块SERVER_ONLY_MODULE_NAMES这是一个模块名数组如[jsdom]传给 Webpack 后会被完全忽略——用于那些只能在 Node 中运行、无法打进浏览器 bundle 的依赖src/Ambidex.server.js 第 215-216 行。如果你引入了这类包却不在这里声明构建时会报无法解析或平台不兼容的错误。附赠CUSTOM_SETTINGS 收纳你自己的配置settings本质上就是一个字典你可以往里放任何自定义值。但注意两点必须能通过 JSON 序列化——整个 settings 会被JSON.stringify后作为 webpack 常量注入客户端代码函数、循环引用之类会直接导致构建失败自定义键名建议放进settings.CUSTOM_SETTINGS下例如STATIC_URL指向你的 CDN避免未来 Ambidex 新增同名设置项时和你的配置撞车。实用技巧settings 文件的三个好习惯按环境拆分文件settings.common.js存放所有环境共享的部分settings.local.js/settings.production.js等小文件只写各自环境的差异改HOST、PORT、ENABLE_HOT_MODULE_REPLACEMENT之类。利用默认值合并官方代码用recursiveCloneWithDefaults把用户配置叠加在默认配置之上见 src/addons/utilities.js你只写差量即可不必复制整份默认设置。在组件里读配置任何 handler 混入 Settings mixin 后调用this.getAmbidexSettings()就能拿到当前完整的 settings 对象服务端还会通过loadSettingsaction 把它同步进 Nuclear store两端行为一致。小结Ambidex 的配置面不大却条条有用NAME/SHORT_NAME管身份HOST/PORT/VM_PORT/BASE_URL/WEBPACK_PORT管访问ENABLE_HOT_MODULE_REPLACEMENT管开发体验TITLE_SEPARATOR/FAV_ICON_URL管外观FILESYSTEM_PATHS管文件位置SERVER_ONLY_MODULE_NAMES管构建边界。把这份清单对照着填进你的 settings 文件服务启动日志里看到Starting mach for 你的应用 on HOST:PORT…的那一刻你的同构 React 应用就跑起来了。【免费下载链接】ambidexEffortlessly host your React app on both the client and the server. Some call it isomorphic JavaScript - we call it Ambidex.项目地址: https://gitcode.com/gh_mirrors/am/ambidex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考