后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本文基于 docs/content/how-to/develop/frontend.md 编写系统梳理 HedgeDoc 前端Next.js React Redux开发中的环境变量配置、单元测试与 Cypress E2E 测试流程、打包产物分析与生产环境调试技巧。读完本文你将掌握HD_BASE_URL等关键环境变量的语义与源码级行为、完整跑通测试套件的命令序列以及无需重新构建即可在生产环境开启调试日志的方法。前端进程识别的环境变量HedgeDoc 前端是一个 Next.js 应用源码位于 frontend其启动与构建行为由一组HD_*/NEXT_PUBLIC_*环境变量控制。官方文档给出的完整变量清单如下变量名可取值说明HD_BASE_URL任意带协议、域名可含目录与端口的 URL必须以斜杠结尾例如http://localhost:3001/前端对外暴露的访问地址。必填服务端渲染SSR需要据此生成资源assetsURL。仅在 production 模式需要手动设置HD_RENDERER_BASE_URL与HD_BASE_URL格式相同渲染器renderer使用独立域名时设置。出于安全考虑推荐让渲染器与编辑器分属不同域名但非强制。可选缺省时回退到HD_BASE_URLNEXT_PUBLIC_USE_MOCK_APItrue、false激活模拟后端mocked backendNEXT_PUBLIC_TEST_MODEtrue、false激活用于测试套件定位元素的额外 HTML 属性HD_BASE_URLSSR 资源地址的唯一来源HD_BASE_URL是唯一必填项前端进程会用它生成编辑器、渲染器以及内部 API 的完整地址。其底层实现在 frontend/src/utils/base-url-from-env-extractor.ts 中BaseUrlFromEnvExtractor类会先以parseUrl来自hedgedoc/commons实现见 commons/src/parse-url/parse-url.ts解析HD_BASE_URL随后依次解析可选的HD_RENDERER_BASE_URL与HD_INTERNAL_API_URL并将三者缓存为BaseUrls供全局消费解析失败非法 URL会直接抛出错误例如undefined isnt a valid URL在 frontend/src/utils/base-url-from-env-extractor.spec.ts 的单元测试中还验证了包含子目录的 URL如https://editor.example.org/asd/会被拒绝并抛出Subdirectories are not allowed因此生产部署时应把前端放在域名根路径或独立端口上结果会被缓存后续extractBaseUrls()调用直接返回缓存值避免重复解析。值得注意的是源码中还存在第三个可选项HD_INTERNAL_API_URL用于指定内部 API 地址测试可见于同一 spec 文件。虽然官方文档的环境变量表格未将其列出但从代码结构看它同样是BaseUrls的一个组成部分需要隔离内部 API 时可以参考该变量。HD_RENDERER_BASE_URL编辑器与渲染器解耦HD_RENDERER_BASE_URL的取值格式与HD_BASE_URL完全相同。源码中通过extractUrlFromEnv(HD_RENDERER_BASE_URL).orElse(editorBaseUrl)实现回退逻辑未设置时渲染器直接复用编辑器的地址。对应单元测试should copy editor base url to renderer base url if url is omitted验证了这一行为。将渲染器部署到独立域名是官方推荐的安全实践——这样编辑器与渲染器之间的 iframe 通信可以获得更清晰的来源隔离HedgeDoc 的渲染器通过 iframe 承载相关实现可参考 frontend/src/components/common/renderer-iframe/renderer-iframe.tsx。NEXT_PUBLIC_*编译期注入的构建开关所有以NEXT_PUBLIC_开头的变量都会在构建阶段被编译进产物编译后无法再修改因此不能通过运行时注入覆盖。其判定逻辑集中在 frontend/src/utils/test-modes.js该文件特意保留为.js因为next.config.js在构建阶段需要引用它NEXT_PUBLIC_TEST_MODE→isTestModeNEXT_PUBLIC_USE_MOCK_API→isMockModeNODE_ENV development→isDevModeANALYZE→isProfilingModetest-modes.js中isPositiveAnswer的取值判定支持yes、1、true大小写不敏感三种真值也就是说NEXT_PUBLIC_TEST_MODE1同样生效。NEXT_PUBLIC_TEST_MODE激活的“额外 HTML 属性”由 frontend/src/utils/cypress-attribute.ts 提供cypressId()在测试模式下向元素注入data-cypress-id属性cypressAttribute()注入data-cypress-前缀的自定义属性非测试模式下这些函数返回空对象/undefined对生产 DOM 零污染。如何正确设置这些变量使用官方 npm 任务官方文档明确建议不要手动设置这些变量而应使用设计好的 npm 任务。这是因为 Mock API 的启用还牵涉到构建脚本对src/pages/api目录的特殊处理。查看 frontend/package.json 中的脚本定义可以看到完整的任务矩阵任务作用pnpm run build生产构建NODE_ENVproductionpnpm run build:mock以NEXT_PUBLIC_USE_MOCK_APItrue构建产物内置模拟 APIpnpm run build:test以NODE_ENVtestNEXT_PUBLIC_TEST_MODEtrue构建测试版pnpm run start:devnext dev开发模式端口默认 3001HD_FRONTEND_PORT可覆盖pnpm run start:dev:mock开发模式 模拟后端并预设HD_BASE_URL/HD_RENDERER_BASE_URLpnpm run start:dev:test开发模式 测试模式供 E2E 使用构建脚本 frontend/build.sh 揭示了 Mock API 的机制构建时若设置了NEXT_PUBLIC_USE_MOCK_API则保留src/pages/api模拟接口目录否则将其移动到临时目录、产出不含 Mock API 的正式包。这也是“使用 designated npm tasks”比手动设置变量更安全的原因——手动设置可能让构建脚本处于不一致的状态。每日重置的 UI 演示实例如果你对 HedgeDoc 新版 UI 感兴趣官方维护着一个每日重置的演示实例即文档中提到的 HedgeDoc.dev 演示站每天重置数据、不做持久化适合快速体验编辑器、渲染器与幻灯片等前端界面效果。注意该实例仅供体验 UI不适合存放重要数据如需长期使用请自行部署。运行测试单元测试JestHedgeDoc 前端的单元测试基于 Jest配置见 frontend/jest.config.ts。运行方式极简pnpm run test该命令会以NODE_ENVtest环境启动 jest见 frontend/package.json 中test脚本。开发过程中还可以使用pnpm run test:watch # 监听模式文件变更自动重跑 pnpm run test:ci # CI 模式带覆盖率收集--coverage测试代码与源码同目录存放、以.spec.ts命名例如前面提到的 frontend/src/utils/base-url-from-env-extractor.spec.ts以及 frontend/src/utils/logger.spec.ts、frontend/src/utils/format-date.spec.ts 等覆盖了工具函数与配置解析等核心逻辑。E2E 测试Cypress端到端测试使用 Cypress测试用例位于 frontend/cypress/e2e如documentTitle.spec.ts、fileUpload.spec.ts、permissions.spec.ts等覆盖了文档标题、文件上传、权限等真实用户场景。官方推荐的标准流程如下以测试模式启动前端test变体是强制要求pnpm run start:dev:test或者先用测试构建产出再启动pnpm run build:test pnpm run start为什么必须用:test变体因为只有设置了NEXT_PUBLIC_TEST_MODEtrue组件才会通过cypressId()渲染data-cypress-id定位属性见 frontend/src/utils/cypress-attribute.tsCypress 才能稳定地按 ID 抓取元素。打开 Cypress 测试加载器pnpm run test:e2e:open选择浏览器并运行测试套件。如需在无头headless浏览器中运行全部测试pnpm run test:e2eCypress 配置见 frontend/cypress.config.tsbaseUrl固定为http://127.0.0.1:3001/默认命令超时 15 秒。此外test:e2e:ci脚本cypress run --record --parallel可用于 CI 环境下的并行执行与结果记录。E2E 测试辅助逻辑如visit-test-editor.ts通过cy.intercept拦截api/private/notes/test的模拟响应位于 frontend/cypress/support编写新用例时可参考。Bundle 分析检查产物优化空间构建后可以分析生产打包产物定位体积与优化问题pnpm run analyze该命令对应 package.json 中的cross-env ANALYZEtrue pnpm run build --profile——先以--profile参数构建这一步会覆盖已有的构建产物再输出分析结果。随后在浏览器中打开生成的.next/server/analyze/server.html即可直观查看各 chunk 与模块的体积构成。test-modes.js中的isProfilingMode正是由ANALYZE变量驱动用于在构建期启用打包分析与性能埋点。生产环境开启调试日志HedgeDoc 前端内置了一个带时间戳与作用域前缀的Logger实现见 frontend/src/utils/logger.ts。其debug()方法默认不输出但在以下三种情况下会启用开发模式isDevMode测试模式isTestMode浏览器localStorage中debugLogging键被置为真值也就是说无需重新构建即可在任意生产实例上开启调试输出。官方文档给出的方法是在浏览器控制台执行window.localStorage.setItem(debugLogging, true);执行后刷新页面Logger.debug(...)的日志便会以带颜色的格式化时间戳输出源码中prefix()为浏览器环境生成了%c样式前缀。想关闭时在控制台清除该键即可window.localStorage.removeItem(debugLogging);这在排查渲染器 iframe、实时协作Yjs/WebSocket等前端疑难问题时非常实用。小结HedgeDoc 前端开发的核心要点可归纳为环境变量分两类——运行期必填的HD_BASE_URL/HD_RENDERER_BASE_URL与编译期注入的NEXT_PUBLIC_*开关前者由BaseUrlFromEnvExtractor解析校验后者驱动 Mock API 与测试模式测试分两层——Jest 单元测试pnpm run test与 Cypress E2Estart:dev:testtest:e2e:open/test:e2eE2E 必须使用:test构建以激活data-cypress-id属性诊断有捷径——pnpm run analyze分析包体积localStorage的debugLogging在生产环境即时开启调试日志。掌握这套体系后无论是本地开发、编写测试还是排查线上问题都能快速找到对应入口。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐OpenMontage生产治理系统质量门控与预算控制的实现原理OpenMontage生产治理系统质量门控与预算控制的实现原理 在当今AI视频制作领域OpenMontage作为首个开源的智能视频生产系统其 生产治理系统人工智能AI Agent音视频媒体生成工作流自动化Arduino ESP32 安装三路径10 分钟搞定 ESP32 开发环境配置完整指南Arduino ESP32 安装三路径10 分钟搞定 ESP32 开发环境配置完整指南 Arduino ESP32 是乐鑫官方的 Arduino 核心支持包嵌入式物联网驱动开发Tekton Pipelines 测试体系全解单元测试、E2E、Conformance 与 Presubmit 实战指南Tekton Pipelines 测试体系全解单元测试、E2E、Conformance 与 Presubmit 实战指南 本文以 Tekton Pipelin云原生CI/CDDevOps后端上一篇如何使用Percollate与Puppeteer打造完美的网页转PDF解决方案下一篇如何看懂React Doctor诊断报告0-100健康评分与错误分级完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HedgeDoc 前端开发实战指南：环境变量、单元/E2E 测试体系与生产调试
后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本文基于 docs/content/how-to/develop/frontend.md 编写系统梳理 HedgeDoc 前端Next.js React Redux开发中的环境变量配置、单元测试与 Cypress E2E 测试流程、打包产物分析与生产环境调试技巧。读完本文你将掌握HD_BASE_URL等关键环境变量的语义与源码级行为、完整跑通测试套件的命令序列以及无需重新构建即可在生产环境开启调试日志的方法。前端进程识别的环境变量HedgeDoc 前端是一个 Next.js 应用源码位于 frontend其启动与构建行为由一组HD_*/NEXT_PUBLIC_*环境变量控制。官方文档给出的完整变量清单如下变量名可取值说明HD_BASE_URL任意带协议、域名可含目录与端口的 URL必须以斜杠结尾例如http://localhost:3001/前端对外暴露的访问地址。必填服务端渲染SSR需要据此生成资源assetsURL。仅在 production 模式需要手动设置HD_RENDERER_BASE_URL与HD_BASE_URL格式相同渲染器renderer使用独立域名时设置。出于安全考虑推荐让渲染器与编辑器分属不同域名但非强制。可选缺省时回退到HD_BASE_URLNEXT_PUBLIC_USE_MOCK_APItrue、false激活模拟后端mocked backendNEXT_PUBLIC_TEST_MODEtrue、false激活用于测试套件定位元素的额外 HTML 属性HD_BASE_URLSSR 资源地址的唯一来源HD_BASE_URL是唯一必填项前端进程会用它生成编辑器、渲染器以及内部 API 的完整地址。其底层实现在 frontend/src/utils/base-url-from-env-extractor.ts 中BaseUrlFromEnvExtractor类会先以parseUrl来自hedgedoc/commons实现见 commons/src/parse-url/parse-url.ts解析HD_BASE_URL随后依次解析可选的HD_RENDERER_BASE_URL与HD_INTERNAL_API_URL并将三者缓存为BaseUrls供全局消费解析失败非法 URL会直接抛出错误例如undefined isnt a valid URL在 frontend/src/utils/base-url-from-env-extractor.spec.ts 的单元测试中还验证了包含子目录的 URL如https://editor.example.org/asd/会被拒绝并抛出Subdirectories are not allowed因此生产部署时应把前端放在域名根路径或独立端口上结果会被缓存后续extractBaseUrls()调用直接返回缓存值避免重复解析。值得注意的是源码中还存在第三个可选项HD_INTERNAL_API_URL用于指定内部 API 地址测试可见于同一 spec 文件。虽然官方文档的环境变量表格未将其列出但从代码结构看它同样是BaseUrls的一个组成部分需要隔离内部 API 时可以参考该变量。HD_RENDERER_BASE_URL编辑器与渲染器解耦HD_RENDERER_BASE_URL的取值格式与HD_BASE_URL完全相同。源码中通过extractUrlFromEnv(HD_RENDERER_BASE_URL).orElse(editorBaseUrl)实现回退逻辑未设置时渲染器直接复用编辑器的地址。对应单元测试should copy editor base url to renderer base url if url is omitted验证了这一行为。将渲染器部署到独立域名是官方推荐的安全实践——这样编辑器与渲染器之间的 iframe 通信可以获得更清晰的来源隔离HedgeDoc 的渲染器通过 iframe 承载相关实现可参考 frontend/src/components/common/renderer-iframe/renderer-iframe.tsx。NEXT_PUBLIC_*编译期注入的构建开关所有以NEXT_PUBLIC_开头的变量都会在构建阶段被编译进产物编译后无法再修改因此不能通过运行时注入覆盖。其判定逻辑集中在 frontend/src/utils/test-modes.js该文件特意保留为.js因为next.config.js在构建阶段需要引用它NEXT_PUBLIC_TEST_MODE→isTestModeNEXT_PUBLIC_USE_MOCK_API→isMockModeNODE_ENV development→isDevModeANALYZE→isProfilingModetest-modes.js中isPositiveAnswer的取值判定支持yes、1、true大小写不敏感三种真值也就是说NEXT_PUBLIC_TEST_MODE1同样生效。NEXT_PUBLIC_TEST_MODE激活的“额外 HTML 属性”由 frontend/src/utils/cypress-attribute.ts 提供cypressId()在测试模式下向元素注入data-cypress-id属性cypressAttribute()注入data-cypress-前缀的自定义属性非测试模式下这些函数返回空对象/undefined对生产 DOM 零污染。如何正确设置这些变量使用官方 npm 任务官方文档明确建议不要手动设置这些变量而应使用设计好的 npm 任务。这是因为 Mock API 的启用还牵涉到构建脚本对src/pages/api目录的特殊处理。查看 frontend/package.json 中的脚本定义可以看到完整的任务矩阵任务作用pnpm run build生产构建NODE_ENVproductionpnpm run build:mock以NEXT_PUBLIC_USE_MOCK_APItrue构建产物内置模拟 APIpnpm run build:test以NODE_ENVtestNEXT_PUBLIC_TEST_MODEtrue构建测试版pnpm run start:devnext dev开发模式端口默认 3001HD_FRONTEND_PORT可覆盖pnpm run start:dev:mock开发模式 模拟后端并预设HD_BASE_URL/HD_RENDERER_BASE_URLpnpm run start:dev:test开发模式 测试模式供 E2E 使用构建脚本 frontend/build.sh 揭示了 Mock API 的机制构建时若设置了NEXT_PUBLIC_USE_MOCK_API则保留src/pages/api模拟接口目录否则将其移动到临时目录、产出不含 Mock API 的正式包。这也是“使用 designated npm tasks”比手动设置变量更安全的原因——手动设置可能让构建脚本处于不一致的状态。每日重置的 UI 演示实例如果你对 HedgeDoc 新版 UI 感兴趣官方维护着一个每日重置的演示实例即文档中提到的 HedgeDoc.dev 演示站每天重置数据、不做持久化适合快速体验编辑器、渲染器与幻灯片等前端界面效果。注意该实例仅供体验 UI不适合存放重要数据如需长期使用请自行部署。运行测试单元测试JestHedgeDoc 前端的单元测试基于 Jest配置见 frontend/jest.config.ts。运行方式极简pnpm run test该命令会以NODE_ENVtest环境启动 jest见 frontend/package.json 中test脚本。开发过程中还可以使用pnpm run test:watch # 监听模式文件变更自动重跑 pnpm run test:ci # CI 模式带覆盖率收集--coverage测试代码与源码同目录存放、以.spec.ts命名例如前面提到的 frontend/src/utils/base-url-from-env-extractor.spec.ts以及 frontend/src/utils/logger.spec.ts、frontend/src/utils/format-date.spec.ts 等覆盖了工具函数与配置解析等核心逻辑。E2E 测试Cypress端到端测试使用 Cypress测试用例位于 frontend/cypress/e2e如documentTitle.spec.ts、fileUpload.spec.ts、permissions.spec.ts等覆盖了文档标题、文件上传、权限等真实用户场景。官方推荐的标准流程如下以测试模式启动前端test变体是强制要求pnpm run start:dev:test或者先用测试构建产出再启动pnpm run build:test pnpm run start为什么必须用:test变体因为只有设置了NEXT_PUBLIC_TEST_MODEtrue组件才会通过cypressId()渲染data-cypress-id定位属性见 frontend/src/utils/cypress-attribute.tsCypress 才能稳定地按 ID 抓取元素。打开 Cypress 测试加载器pnpm run test:e2e:open选择浏览器并运行测试套件。如需在无头headless浏览器中运行全部测试pnpm run test:e2eCypress 配置见 frontend/cypress.config.tsbaseUrl固定为http://127.0.0.1:3001/默认命令超时 15 秒。此外test:e2e:ci脚本cypress run --record --parallel可用于 CI 环境下的并行执行与结果记录。E2E 测试辅助逻辑如visit-test-editor.ts通过cy.intercept拦截api/private/notes/test的模拟响应位于 frontend/cypress/support编写新用例时可参考。Bundle 分析检查产物优化空间构建后可以分析生产打包产物定位体积与优化问题pnpm run analyze该命令对应 package.json 中的cross-env ANALYZEtrue pnpm run build --profile——先以--profile参数构建这一步会覆盖已有的构建产物再输出分析结果。随后在浏览器中打开生成的.next/server/analyze/server.html即可直观查看各 chunk 与模块的体积构成。test-modes.js中的isProfilingMode正是由ANALYZE变量驱动用于在构建期启用打包分析与性能埋点。生产环境开启调试日志HedgeDoc 前端内置了一个带时间戳与作用域前缀的Logger实现见 frontend/src/utils/logger.ts。其debug()方法默认不输出但在以下三种情况下会启用开发模式isDevMode测试模式isTestMode浏览器localStorage中debugLogging键被置为真值也就是说无需重新构建即可在任意生产实例上开启调试输出。官方文档给出的方法是在浏览器控制台执行window.localStorage.setItem(debugLogging, true);执行后刷新页面Logger.debug(...)的日志便会以带颜色的格式化时间戳输出源码中prefix()为浏览器环境生成了%c样式前缀。想关闭时在控制台清除该键即可window.localStorage.removeItem(debugLogging);这在排查渲染器 iframe、实时协作Yjs/WebSocket等前端疑难问题时非常实用。小结HedgeDoc 前端开发的核心要点可归纳为环境变量分两类——运行期必填的HD_BASE_URL/HD_RENDERER_BASE_URL与编译期注入的NEXT_PUBLIC_*开关前者由BaseUrlFromEnvExtractor解析校验后者驱动 Mock API 与测试模式测试分两层——Jest 单元测试pnpm run test与 Cypress E2Estart:dev:testtest:e2e:open/test:e2eE2E 必须使用:test构建以激活data-cypress-id属性诊断有捷径——pnpm run analyze分析包体积localStorage的debugLogging在生产环境即时开启调试日志。掌握这套体系后无论是本地开发、编写测试还是排查线上问题都能快速找到对应入口。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐OpenMontage生产治理系统质量门控与预算控制的实现原理OpenMontage生产治理系统质量门控与预算控制的实现原理 在当今AI视频制作领域OpenMontage作为首个开源的智能视频生产系统其 生产治理系统人工智能AI Agent音视频媒体生成工作流自动化Arduino ESP32 安装三路径10 分钟搞定 ESP32 开发环境配置完整指南Arduino ESP32 安装三路径10 分钟搞定 ESP32 开发环境配置完整指南 Arduino ESP32 是乐鑫官方的 Arduino 核心支持包嵌入式物联网驱动开发Tekton Pipelines 测试体系全解单元测试、E2E、Conformance 与 Presubmit 实战指南Tekton Pipelines 测试体系全解单元测试、E2E、Conformance 与 Presubmit 实战指南 本文以 Tekton Pipelin云原生CI/CDDevOps后端上一篇如何使用Percollate与Puppeteer打造完美的网页转PDF解决方案下一篇如何看懂React Doctor诊断报告0-100健康评分与错误分级完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
