amis：百度低代码前端页面框架安装与使用指南

本文是 amis（百度前端低代码框架） GitHub 官方 README 的完整中文整理版，命令、端口、版本要求均与官方仓库保持一致。

官方信息

项目简介

amis 是一个前端低代码框架，通过 JSON 配置就能生成各种后台页面，极大减少开发成本，甚至可以不需要了解前端。它把"页面长什么样、数据从哪来、表单怎么校验、按钮点了干什么"全部抽象成一份 JSON Schema，再由 amis 渲染器在浏览器里把它渲染成真实可用的管理页面：表格、表单、详情页、筛选、弹窗、CRUD 等后台常见组件开箱即用。对运维、运营、内部系统的开发者来说，意味着不用写一行 React 代码，拼好 JSON 就得到一个能跑的后台。

官方提供两套文档入口：国内访问 国内文档，国外访问 国外文档；不想手写 JSON 的用户可以直接打开在线的 可视化编辑器 拖拽生成配置；想直接看一个完整后台长什么样，可以克隆官方的 amis-admin 示例项目。需要说明的是，amis 只覆盖前端低代码；如果需要一个完整的低代码平台（含后端、权限、流程），官方推荐使用 爱速搭。

amis 的使用方式可以概括成一句话：写一份描述页面的 JSON，交给 amis 渲染器运行。这份 JSON 里会声明页面类型（表单、CRUD、详情、wizard 向导等）、每个控件的属性（字段名、默认值、校验规则）、接口地址（数据从哪个接口拉、表单提交到哪个接口）、以及按钮行为（弹框、跳转、刷新、下发动作）。渲染器拿到 JSON 后，在浏览器里把它翻译成真实的 DOM 与交互逻辑。常见的管理后台需求——列表分页、多条件筛选、行内编辑、批量操作、详情抽屉、二级弹窗、权限按钮——都由内置渲染器承担，使用者只需在 JSON 里开启对应配置，不必自己写组件。对中小团队而言，这种模式把"后台页面开发"从前端工程任务降级成了配置工作，产品、测试、运维同学也能照着文档改出自己要的页面。从仓库结构上看，amis 是一个 npm workspaces 管理的 monorepo：核心渲染器位于 packages/amis，可视化编辑器位于 packages/amis-editor，examples/ 目录下存放各种示例页面（如 examples/pages/simple）。日常开发时，npm start 会同时把这些包的源码编译成可访问的静态站点，所以你看到的示例地址 examples/pages/simple 和编辑器地址 packages/amis-editor/ 都是同一个本地 dev server 下的路径。

环境要求

参与 amis 本身的开发（而不是使用 amis 搭页面）时，官方给出的工具链要求是：

• 推荐使用 Node.js 12 / 14 / 16；
• npm 7 及以上版本，因为仓库用到了 npm workspaces 功能；
• 仓库在国内从 GitHub 下载慢时，可以改用 Gitee 镜像：gitee.com/baidu/amis。

README 顶部的徽章还给出了项目的实时状态：GitHub Actions 的构建状态、开源协议、npm 上的发布版本号、主力语言、Codecov 覆盖率，以及最近一次提交时间。这些信息可以在克隆仓库前先帮你判断项目是否仍在活跃维护、当前 npm 版本号是多少。对使用方来说，npm 版本号对应你在自己项目里 npm i amis 时锁定的版本；对贡献方来说，构建与覆盖率徽章是 PR 能否被合并的基线信号。

部署与启动步骤

克隆仓库后，先安装项目依赖：

# 安装项目 npm 依赖，在 node 12 下会有报错但不影响正常使用
npm i --legacy-peer-deps

注意这里必须加 --legacy-peer-deps，否则 monorepo 内部各包之间的依赖会在安装阶段就报错。这是因为 amis 仓库用 npm workspaces 同时管理着渲染器、编辑器、示例等多个包，包与包之间又互相声明了 peer 依赖，npm 7 之后对 peer 依赖的校验变严格，遇到版本不匹配会直接拒绝安装；加上 --legacy-peer-deps 后会回到 npm 6 的宽松行为，只警告不报错。官方也提示在 Node 12 下安装过程中可能看到一些报错信息，但不影响后续使用。依赖装好后启动开发服务：

# 启动项目，等编译结束后通过 http://127.0.0.1:8888/examples/pages/simple 访问
npm start

启动成功后，浏览器访问 http://127.0.0.1:8888/examples/pages/simple 即可看到最简单的示例页面。如果你要开发的是 amis 可视化编辑器本身，需要访问的地址是 http://127.0.0.1:8888/packages/amis-editor/。

之所以有两个入口，是因为 amis 仓库本身既是渲染器源码，也是一套在线示例站：npm start 启动的开发服务器把 examples 下的示例页面、编辑器包、文档站点全部编译在 8888 端口下，改 packages/amis 的源码后，示例页会热更新，方便你一边改渲染器一边在浏览器里看效果。

使用方法：开发与测试命令

README 中"开发指南"一节列出的全部命令，按使用场景整理如下。这里的命令都是针对"参与 amis 框架本身开发"的场景；如果你只是用 amis 搭页面，直接看官方文档里的 Schema 示例即可，不需要把整个仓库跑起来。

一个典型的贡献流程是：先 npm i --legacy-peer-deps 装好依赖，npm start 起本地 dev server，在 examples/pages/simple 里复现或调试问题；改完代码后 npm run build 编译，再跑对应的 Jest 用例验证行为；确认无误后把改动连同新测试一起提交到 feat-xxx 分支并发 PR。下面把 README 里的命令逐组拆开说明。

执行单元测试

官方特别提示：本地改完代码后，跑测试用例之前必须先执行 npm run build 完成编译，因为 Jest 不直接支持 TypeScript。

# 安装依赖
npm i --legacy-peer-deps

# 执行构建
npm run build

# 执行全部测试用例
npm test --workspaces

# 只跑某个用例，<spec-name> 为用例名称，比如 inputImage
npm test --workspace amis -- -t <spec-name>

# 直接运行某个单测文件
./node_modules/.bin/jest packages/amis/__tests__/renderers/Form/buttonToolBar.test.tsx

# 运行某个单测文件里的某个例子
./node_modules/.bin/jest packages/amis/__tests__/renderers/Form/buttonToolBar.test.tsx -t 'Renderer:button-toolbar'

查看覆盖率与更新快照

# 查看测试用例覆盖率
npm run coverage

# 更新所有 snapshot
npm run update-snapshot

# 只更新单个 snapshot，<spec-name> 为用例名称，比如 inputImage
npm run update-snapshot --workspace amis -- -t <spec-name>

amis 大量使用快照测试（snapshot）来校验渲染输出是否符合预期：改完渲染器后，快照会记录一份当时的 DOM 输出，下次测试把新输出和快照逐字节对比，不一致即失败。如果是有意为之的 UI 变更，就用上面的命令更新快照；如果是意料之外的 diff，则要回去检查代码。

发布版本

# 发布到内部 registry
npm run publish

# 发布外网环境：先通过下面命令设置版本号
npm run version
npm run release

发布命令分两种：npm run publish 面向内部 registry，用于团队内部验证；对外发布时先用 npm run version 设置新版本号，再执行 npm run release。普通使用者不需要执行发布命令，只有仓库维护者在发版时才会用到。普通使用者通过 npm 安装 amis 包时，直接看官方文档里的引入方式即可，不需要把整个 monorepo 跑起来。

如何贡献

官方要求采用分支开发：先从主干拉出特性分支，命名形如 feat-xxx：

git checkout -b feat-xxx

开发提交后，用 git push --set-upstream origin feat-xxx 创建远程分支，然后通过终端提示给出的 https://github.com/xxx/amis/pull/new/feat-xxx 链接提交 Pull Request。官方要求代码使用 TypeScript 编写，所有合理的改动、新的公用渲染器、测试用例或文档提交都会被接收。

社区交流方面，官方 README 里留下了两个百度如流群：如流群 3395342 与如流群 2：5511067，遇到问题或想参与讨论可以加群。仓库 README 还通过一张贡献者图片展示了所有提交过代码的人，新贡献者的 PR 被合并后也会出现在这张图里。

需要再次强调使用边界：amis 解决的是"前端页面"的低代码问题，它本身不提供后端服务、数据库、权限模型和流程引擎。如果你只想快速搭一个内部管理后台，并且后端接口已经就绪，amis 就够用；如果你需要的是业务人员也能自己搭系统的完整低代码平台，那就应该用官方的 爱速搭，它在 amis 渲染能力之上补齐了数据源、权限、表单流程与发布体系。

常见问题（FAQ）

• 问：用 amis 搭后台需要会 React 吗？ 答：不需要。它的使用方式是写 JSON 配置，官方文档里有大量 Schema 示例；只有当你要给 amis 贡献新渲染器、或者定制编辑器时，才需要 TypeScript/React 能力。
• 问：npm i 为什么要加 --legacy-peer-deps？ 答：这是一个 npm workspaces 的 monorepo，内部包互相依赖，不加该参数时 npm 7 会因为 peer 依赖严格校验而报错；官方说明即使在 Node 12 下出现一些安装报错，也不影响正常使用。
• 问：开发服务起来后访问哪个地址？ 答：渲染器示例走 http://127.0.0.1:8888/examples/pages/simple，编辑器开发走 http://127.0.0.1:8888/packages/amis-editor/。
• 问：为什么改完代码跑 Jest 会失败？ 答：因为 Jest 不支持直接跑 TypeScript，必须先 npm run build 完成编译，再执行 npm test --workspaces。
• 问：snapshot 测试报错怎么办？ 答：如果是预期内的 UI 变更，用 npm run update-snapshot 全量更新，或加 --workspace amis -- -t <spec-name> 只更新单个用例的快照。
• 问：GitHub 下载慢怎么办？ 答：官方提供 Gitee 镜像 gitee.com/baidu/amis。
• 问：amis 和爱速搭什么关系？ 答：amis 是开源的前端低代码框架，只负责前端页面渲染；爱速搭是百度提供的完整低代码平台，在 amis 之上补齐了后端、权限、流程等能力。
• 问：想给 amis 加一个自定义渲染器要做什么？ 答：按官方贡献流程，从主干切出 feat-xxx 分支，用 TypeScript 实现新渲染器并在 packages/amis 下补充对应测试用例，提交 PR 即可。官方明确说明"新的公用渲染器、用例或者文档的提交都会被接收"。
• 问：本地 dev server 端口是多少？ 答：固定 8888，不用自己配端口；渲染示例走 http://127.0.0.1:8888/examples/pages/simple，编辑器开发走 http://127.0.0.1:8888/packages/amis-editor/。
• 问：Node 版本一定要选 12/14/16 吗？ 答：官方推荐这三个版本。在 Node 12 下 npm i 可能出现报错，但官方说明不影响正常使用；npm 则要求 7+，因为仓库用了 workspaces 功能。
• 问：改了一个渲染器想只验证它的测试怎么办？ 答：用 npm test --workspace amis -- -t <spec-name>，或直接 ./node_modules/.bin/jest <测试文件路径>，也可以再加 -t '用例名' 把范围缩到单个用例。
• 问：示例页面和编辑器的地址记不住怎么办？ 答：两个地址都在 README 里写死了：渲染器示例 http://127.0.0.1:8888/examples/pages/simple，编辑器开发 http://127.0.0.1:8888/packages/amis-editor/。dev server 是 npm start 自动起的，端口固定 8888。
• 问：为什么 README 大半内容在讲开发而不是怎么用？ 答：这份 README 本身定位就是"参与开发 amis 才需要看的"，README 开头明确说"以下是参与开发 amis 才需要看的，使用请看前面的文档"。真正怎么用 amis 搭页面，去官方文档站按组件逐个学即可。
• 问：提交 PR 有什么格式要求？ 答：官方只要求用 TypeScript 编写、从 feat-xxx 分支提 PR；合理改动、新渲染器、用例、文档都会被接收。
• 问：Codecov 覆盖率重要吗？ 答：覆盖率徽章反映的是整体测试覆盖比例，贡献新渲染器时通常要补对应用例，PR 里覆盖率不能明显下滑，这是社区约定俗成的门槛。
• 问：想直接在浏览器里试 JSON 而不搭环境？ 答：用官方在线的 可视化编辑器，它就是一个可以拖拽、即时预览 amis JSON 渲染效果的沙盒，适合初次接触者零安装体验。
• 问：如流群怎么加？ 答：README 里给了两个群号：3395342 与 5511067，在百度如流客户端搜索群号即可加入，适合日常交流与问题反馈。

跳转链接

• 仓库：github.com/baidu/amis
• 国内文档：aisuda.bce.baidu.com/amis
• 国外文档：baidu.github.io/amis
• 可视化编辑器 Demo：aisuda.github.io/amis-editor-demo
• 示例后台：amis-admin
• 完整低代码平台：爱速搭
• Gitee 镜像：gitee.com/baidu/amis

以上链接均为官方 README 中列出的入口，初次接触建议从国内文档站读起，再用可视化编辑器亲手拼一个 CRUD 页面，最后回到 GitHub 仓库阅读开发指南，参与框架本身的贡献。