文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
149 lines
5.3 KiB
Markdown
149 lines
5.3 KiB
Markdown
# C5 任务:amis 6.13.0 Fork 构建预演报告
|
||
|
||
**任务编号**:EIP4 M0 – C5
|
||
**执行日期**:2026-06-10
|
||
**结论**:**构建成功 ✅**
|
||
|
||
---
|
||
|
||
## 一、环境
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 操作系统 | macOS Darwin 25.5.0 |
|
||
| Node.js | v22.22.3 |
|
||
| npm | 10.9.8 |
|
||
| 仓库来源 | 浅克隆 amis tag 6.13.0(/Users/zhengwr/workspace/eip3/amis-fork) |
|
||
|
||
---
|
||
|
||
## 二、构建命令序列
|
||
|
||
### 2.1 依赖安装
|
||
|
||
```bash
|
||
cd /Users/zhengwr/workspace/eip3/amis-fork
|
||
npm install --legacy-peer-deps
|
||
```
|
||
|
||
- 耗时:约 7 分钟
|
||
- 安装包数:2794 个
|
||
- 说明:使用 `--legacy-peer-deps` 绕过 peer dependency 冲突(amis monorepo 中各子包相互依赖版本声明不严格);Node 22 下正常通过,**未触发 openssl ERR_OSSL 问题**(rollup/fis3 本身不依赖老 openssl API,无需 `--openssl-legacy-provider`)
|
||
|
||
### 2.2 子包顺序构建
|
||
|
||
amis 是 monorepo,packages/amis 依赖其他子包的 `lib/` 产物,必须按依赖拓扑顺序构建:
|
||
|
||
```bash
|
||
# 1. 基础公式库(无依赖)
|
||
cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-formula
|
||
npm run build # rollup, ~1s
|
||
|
||
# 2. 核心库(依赖 amis-formula)
|
||
cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-core
|
||
npm run build # rollup, ~4s
|
||
|
||
# 3. UI 组件库(依赖 amis-core)
|
||
cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-ui
|
||
npm run build # rollup + SCSS, ~25s
|
||
|
||
# 4. amis 主包 + SDK(依赖以上全部)
|
||
cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis
|
||
npm run build # rollup + fis3 + postcss + build-schemas, ~60s
|
||
```
|
||
|
||
**注意**:直接从根目录执行 `npm run build --workspaces` 理论上可行,但 npm workspaces 并行执行会因依赖顺序竞争失败。按手动拓扑顺序逐包构建是安全做法。
|
||
|
||
---
|
||
|
||
## 三、遇到的坑与绕法
|
||
|
||
| 坑 | 根因 | 绕法 |
|
||
|----|------|------|
|
||
| 直接 `cd packages/amis && npm run build` 报 `Cannot find module 'amis-core'` | 子包尚未构建,`lib/` 不存在;rollup 从 workspace symlink 找不到 TS 声明 | 先逐包构建 formula → core → ui,再构建 amis |
|
||
| rollup 警告 `Unknown output options: commonConfig` | rollup.config.js 中使用了旧版 API,当前 rollup 2.79 已不支持 `commonConfig` 字段 | 仅为警告,不影响产物生成,忽略即可 |
|
||
| SCSS `sass deprecation: Using / for division` 大量警告 | dart-sass 新版本废弃 `/` 除法语法 | 仅为警告,CSS 仍正常生成,忽略 |
|
||
| fis3 `Can't resolve fs/stream in xlsx.js` | xlsx.js 包含 Node.js 内置模块引用,fis3 浏览器打包时找不到 | 仅为警告(xlsx 会 graceful fallback),产物可用 |
|
||
| 端口 18080 被占用 | 本机其他进程占用 | 换 18081 端口 |
|
||
|
||
**openssl 问题**:Node 22 + rollup 2.x + fis3 3.5 组合**未触发** ERR_OSSL_EVP_UNSUPPORTED,无需 `NODE_OPTIONS=--openssl-legacy-provider`。
|
||
|
||
---
|
||
|
||
## 四、产物清单与体积
|
||
|
||
构建产出目录:`packages/amis/sdk/`,已复制至:
|
||
`src/main/resources/static/sdk-local/`
|
||
|
||
| 文件 | 体积 | 说明 |
|
||
|------|------|------|
|
||
| `sdk.js` | **2.0 MB** | 核心 JS,含 amisRequire 全局导出 |
|
||
| `sdk.css` | 2.5 MB | 默认 cxd 主题样式 |
|
||
| `helper.css` | 952 KB | 辅助样式 |
|
||
| `iconfont.css` | 152 KB | 图标字体 CSS |
|
||
| `iconfont.ttf` | 192 KB | 图标字体 TTF |
|
||
| `iconfont.woff` | 116 KB | 图标字体 WOFF |
|
||
| `iconfont.eot` | 176 KB | 图标字体 EOT(IE 兼容) |
|
||
| `iconfont.svg` | 696 KB | 图标字体 SVG |
|
||
| `ang.css` / `antd.css` / `dark.css` / `cxd.css` | 各约 1-2 MB | 主题变体 |
|
||
| `sdk-ie11.css` | - | IE11 兼容版(PostCSS 处理后) |
|
||
| `charts.js` / `markdown.js` / `codemirror.js` 等 | - | 按需加载的分包 |
|
||
| **sdk-local/ 总计** | **52 MB** | 含所有主题、分包、字体 |
|
||
|
||
---
|
||
|
||
## 五、替换 CDN 的改法
|
||
|
||
原 `amis.html`(CDN 引用):
|
||
```html
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/amis@6.13.0/sdk/sdk.css"/>
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/amis@6.13.0/sdk/helper.css"/>
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/amis@6.13.0/sdk/iconfont.css"/>
|
||
<script src="https://cdn.jsdelivr.net/npm/amis@6.13.0/sdk/sdk.js"></script>
|
||
```
|
||
|
||
替换为本地路径(`amis-local.html`):
|
||
```html
|
||
<link rel="stylesheet" href="sdk-local/sdk.css"/>
|
||
<link rel="stylesheet" href="sdk-local/helper.css"/>
|
||
<link rel="stylesheet" href="sdk-local/iconfont.css"/>
|
||
<script src="sdk-local/sdk.js"></script>
|
||
```
|
||
|
||
已生成文件:`src/main/resources/static/amis-local.html`
|
||
|
||
---
|
||
|
||
## 六、冒烟验证
|
||
|
||
```bash
|
||
cd src/main/resources/static
|
||
python3 -m http.server 18081
|
||
|
||
# 验证结果:
|
||
curl -I http://localhost:18081/sdk-local/sdk.js
|
||
# → HTTP 200
|
||
|
||
wc -c sdk-local/sdk.js
|
||
# → 2,060,802 字节(约 2 MB,>1 MB ✅)
|
||
|
||
grep -o 'amisRequire' sdk-local/sdk.js | head -1
|
||
# → amisRequire ✅
|
||
```
|
||
|
||
所有冒烟检查通过。
|
||
|
||
---
|
||
|
||
## 七、结论
|
||
|
||
| 项目 | 结果 |
|
||
|------|------|
|
||
| 构建结果 | **成功** |
|
||
| Node 22 兼容性 | **兼容**,无需降级或 openssl 绕法 |
|
||
| SDK 产物 | sdk.js(2MB)+ sdk.css(2.5MB)+ 字体图标完整 |
|
||
| CDN 替换 | 完成(amis-local.html) |
|
||
| 止损 S2 评估 | **暂不触发**,amis 6.13.0 在 Node 22 本机环境可正常构建,无需切换备选方案 |
|
||
|
||
**下一步建议**:将 sdk-local/ 纳入版本管理或 CI 构建流程,部署时直接使用本地产物,彻底消除对 CDN 的依赖。
|