工程实践总览

本章节面向维护 ng-mfe 仓库、负责 CI/CD 与线上运维的工程师,回答三个问题:质量如何被守住、性能如何被约束、发布如何被执行。所有数字与命令均来自仓库源码(package.json、.github/workflows/、.size-limit.json、tools/),可自行复核。

工程全景

维度	机制	落点(源码)	门禁位置
代码规范	ESLint + Prettier check	根 `package.json` 脚本	CI `lint` job
单元/集成测试	vitest 项目化聚合(packages + integration-tests)	根 `vitest.config.ts`	CI `test` job(`test:coverage`)
E2E 测试	Playwright,dev/deploy 双模式	`playwright.config.ts`、`e2e/`	`e2e.yml`(deploy 模式)
类型检查	4 个示例 tsconfig 逐一 `tsc --noEmit`	`examples:check` 脚本	CI `typecheck` job
体积预算	size-limit(gzip 口径),9 条上限	`.size-limit.json`	CI `size-check` job
Zoneless 纪律	禁 zone.js 依赖/import、强制 provideZonelessChangeDetection、禁 inject(NgZone)	`scripts/guard-zoneless.mjs`	CI `zoneless-guard` job
构建	`nx run-many --target=build`	根 `package.json`	CI `build` job
发布	tag 触发 → 版本同步 → 混淆 → 产物校验 → npm 发布 → GitHub Release	`.github/workflows/release.yml`	tag `v*` / 手动触发

CI(ci.yml)共 6 个 job,全部使用 bun install --frozen-lockfile,在 push / PR 到 main 时触发,同 ref 并发自动取消:

job	名称	关键步骤
`lint`	Lint & Format	`bun run lint` + `bun run format:check`
`test`	Unit Tests	`bun run test:coverage`,上传 coverage artifact(保留 14 天)
`build`	Build	`nx run-many --target=build`(fetch-depth: 0 以支持 nx affected)
`typecheck`	Type Check	`bun run examples:check`(4 个示例 tsconfig 逐一 `tsc --noEmit`)
`size-check`	Size Check	先 `bun run build` 再 `bun run size:check`
`zoneless-guard`	Zoneless Guard	`bun run guard:zoneless`

另有三条独立工作流:e2e.yml(deploy 产物 + 全量 E2E)、release.yml(tag v* 触发发布)、deploy-preview.yml(PR 部署产物 artifact)。

环境要求

Node.js >= 20.0.0(根 package.json engines 约束);
包管理:bun(CI 使用 bun install --frozen-lockfile);本地 npm install 亦可,常用脚本以 npm run 形式给出;
E2E 需要 Playwright chromium(bunx playwright install --with-deps chromium);
示例开发端口约定:portal 4200,angular-sub 4201,vue-sub 4202,react-sub 4203,wc-sub 4204,custom-sub 4205;部署预览统一 8080。

快速命令表

以下命令均定义在根 package.json,可直接复制使用:

场景	命令
安装依赖	`bun install`(或 `npm install`)
全量测试(单测 + 集成)	`npm run test`
覆盖率	`npm run test:coverage`
仅集成测试	`npm run test:integration`
监听模式	`npm run test:watch`
E2E(dev 模式,自动起 6 个 server)	`npm run e2e:dev`
E2E(deploy 模式,8080)	`npm run e2e:deploy`
E2E 交互式 UI / 报告	`npm run e2e:ui` / `npm run e2e:report`
代码检查 / 格式检查	`npm run lint` / `npm run format:check`
示例类型检查	`npm run examples:check`
构建全部包	`npm run build`
本地起全部示例(portal + 5 子应用)	`npm run examples:start`
单起某个应用	`npm run start:portal` / `start:angular-sub` / `start:vue-sub` / `start:react-sub` / `start:wc-sub` / `start:custom-sub`
Zoneless 守卫	`npm run guard:zoneless`
体积预算检查	`npm run size:check`(仅查看用 `npm run size`)
部署产物构建 / 预览	`npm run deploy:build` / `npm run deploy:preview`
文档站开发 / 构建 / 预览	`npm run docs:dev` / `docs:build` / `docs:preview`

分层阅读指引

建议按以下顺序阅读本章节,由近及远覆盖"改代码 → 上线"的完整链路:

测试体系 — 三层测试金字塔(单元/集成/E2E)的规模、运行方式与 @ng-mfe/testing 工具;改任何包之前先看这页,确认你新增的行为有对应测试层。
性能实践 — 体积预算表(size-limit 真实上限)与框架内建的加载/运行时/网络/内存优化机制;不含臆造的 benchmark,只讲可验证的机制与预算。
安全实践 — 信任模型、沙箱与 CSS 隔离、XSS 防护点、发布混淆;明确区分"已实现"与"建议/规划中"。
生产部署 — deploy:build 产物结构与机制、nginx 示例配置逐段解读、release 流水线与发布校验;CDN/灰度/回滚等仅作为部署建议(非内置)。

每页自成一体,也可按需直接跳转;页面间通过"相关链接"互相引用。

一条改动的主流路径

以"给 @ng-mfe/services 增加一个缓存行为"为例,工程链路如下:

bash

npm run test:integration     # 1. 先确认相关集成用例当前是绿的
# ……编写实现与用例(cache-patterns.spec / cache-multilevel.spec)……
npm run test                 # 2. 全量单测 + 集成
npm run lint && npm run examples:check   # 3. 规范与类型
npm run size:check           # 4. 体积预算(改 core 时尤其重要)
npm run e2e:dev              # 5. E2E 验收(dev 模式自动起 6 个 server)
git push                     # 6. CI 六个 job + deploy 模式 E2E 把关

发布不在日常路径中:打 v* tag 触发 release.yml,经混淆与产物校验后发布 npm 并创建 GitHub Release(详见生产部署)。

与其他章节的关系

面向业务的部署步骤(目录规划、URL 约定)见使用指引的部署指南。
遇到运行时故障(白屏、加载失败、状态异常)先查故障排查,再回到本章节核对是否门禁/配置问题。
验证某个能力是否真实可用,参考验证指南。
各机制的内部原理见架构总览及其子页。

质量基线速览

以下数字来自仓库当前状态(测试用例数随开发推进会变化,以本地 npm run test 输出为准):

packages 单元测试约 1617 个用例;
集成测试(integration-tests)307 个用例、17 个 spec 文件;
E2E(Playwright)18 个 spec 文件、109 个用例,chromium 单浏览器、workers: 1、CI 失败重试 2 次;
体积预算共 9 条(core 15KB、event-bus 5KB、shared-state 8KB、sandbox 12KB、util 6KB、adapters/angular 10KB、vue 8KB、react 8KB、devtools 5KB,gzip 口径)。

工程实践总览 ​

工程全景 ​

环境要求 ​

快速命令表 ​

分层阅读指引 ​

一条改动的主流路径 ​

与其他章节的关系 ​

质量基线速览 ​

相关链接 ​