文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.3 KiB
5.3 KiB
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 依赖安装
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/ 产物,必须按依赖拓扑顺序构建:
# 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 引用):
<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):
<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
六、冒烟验证
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 的依赖。