amis-cmp-cli

v1.1.9

Published

9 days ago

前端脚手架：amis 自定义组件开发工具，支持 react 和 vue2.0 技术栈。

0High
0Medium
0Low

wibetter

amis-cli 自定义组件开发工具

Amis 自定义组件开发工具

amis-cmp-cli 是 Amis 自定义组件开发工具，基于 AKFun 的工程能力，提供初始化、编译构建、预览调试、热更新、多技术栈支持和发布等功能。

主要特性

零配置: 内置默认配置，开箱可用；
多技术栈: 支持 Vue2、React、React+TypeScript 自定义组件的调试、构建与发布；
多构建场景: 本地预览（含热更新/代理）、外链调试、库构建（UMD/ESM）、部署&发布；
灵活可配: 支持构建入口、别名、代理、SASS 注入、ESLint/StyleLint、Babel/Loader/Plugin 扩展等配置；
样式与规范: 内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint；
发布至 CDN: 内置发布到对象存储（OSS）的能力，支持自定义对象存储配置；
内置模块共享机制: 支持自定义组件之间共享模块和复用。

内置的自定义组件模板

创建自定义组件时（执行初始化命令 amis init）可选用。

React + TS 模板: react-ts-custom-cmp-template 内置信息卡片列表展示组件示例
React 模板(非 TS): react-custom-cmp-template
Antd 模板: antd-custom-cmp-template 内置 Antd UI 组件实现的数据仪表板展示组件示例
Echarts 模板: echarts-custom-cmp-template Echarts 图表自定义组件（含高德地图展示组件示例）
Vue2 模板: vue2-custom-cmp-template Vue2.0 自定义组件

快速开始

1) 全局安装自定义组件开发工具

yarn global add amis-cmp-cli
# 或
npm i -g amis-cmp-cli

2) 创建自定义组件项目

# 方式一：创建空的自定义组件项目
amis create project

# 方式二：根据模板创建自定义组件项目（默认 React+TS，可用 -t 指定模板，-n 指定自定义组件名称）
amis init

3) 进入自定义组件项目根目录，安装依赖并运行

cd xxCmpProject

4) 创建自定义组件

# 在当前项目中创建一个自定义组件
amis create cmp

默认在当前项目 src/components/ 目录下新增自定义组件。

5) 本地预览自定义组件内容

# 预览自定义组件内容
amis preview

执行成功后，默认自动打开本地浏览器预览自定义组件内容。

6) 外链调试（在线上页面设计器端预览与调试）

amis linkDebug

需在 amis 页面设计器端挂载控制台输出的外链脚本地址，方可在页面设计器端使用当前自定义组件。

常用命令说明

amis init: 交互式创建自定义组件（支持 -t、--name）;
amis create project: 创建自定义组件项目（支持 --name）;
amis create cmp: 在当前项目中创建一个自定义组件（支持 --name）;
amis preview: 本地预览自定义组件内容（支持 --name），默认支持热更新与接口代理;
amis linkDebug: 外链调试模式，在平台端页面设计器中调试自定义组件;
amis publish2oss: 构建并上传到对象存储（支持 --name，可自定义配置对象存储）;

开发须知

1）默认自动识别自定义组件

自动生成入口配置: 当 entry 未配置时，自动从 src/components 目录下扫描并识别自定义组件，src/components 下的子目录名称作为自定义组件的名称，并以其目录下的 index.ts/.tsx/.js/.jsx 文件作为组件内容文件，plugin.[tj]s 作为插件内容文件；
自动注册自定义组件: 当 entry 未配置时，自动生成自定义组件注册文件和插件注册文件，并注入到构建脚本中，无需用户手动编写注册文件（amis-register）。默认均注册为 amis普通组件（renderer），如需注册成 amis表单组件，组件目录请以 input 开头（比如 input-xxCmp）。

2）设置自定义组件属性配置项

通过 amis init 初始化的自定义组件，默认自带组件插件文件，所有和页面设计器关联的信息均在此文件中定义（详细见 plugin 文件中的注释说明）。其中 panelBodyCreator 用于添加自定义组件的属性配置面板。

3）本地调试自定义组件

1. 启动外链调试模式

amis linkDebug

启动成功后，当前命令控制台会输出一个可使用的外链脚本地址（通常为 http://localhost:1024/index.js）。

2. 打开线上页面设计器，并添加外链脚本地址

访问线上页面设计器打开任意页面，在左侧外部链接管理面板添加外链脚本地址，添加完成后即可在此页面设计器 / 组件物料面板中看到对应自定义组件。

4）发布自定义组件至CDN

执行 amis publish2oss 即可构建对应自定义组件，并自动将构建后资源上传到对象存储（OSS）中。

发布前请确保

package.json 的 name 唯一
version 不重复
可按需配置对象存储参数（支持自定义），默认使用内置对象存储配置。

支持自定义对象存储配置

module.exports = {
  publish2oss: {
    // 用于构建并发布至 OSS 的相关配置
    //【特别说明】以下配置项都自带默认值，非必填。如需自定义请自行配置。
    // NODE_ENV: 'production',
    // cssExtract: false, // 不额外提取css文件
    ossType: 'ali', // oss类型：ali、baidu
    ossConfig: {
      endpoint: 'https://oss-cn-beijing.aliyuncs.com',
      AccessKeyId: 'xxx',
      AccessKeySecret: 'xx',
      bucket: 'amis-cmp-xx-bucket' // 存储桶名称
    },
    assetsRoot: resolve('dist') // 上传指定目录下的脚本文件
  },
}

支持发布指定自定义组件

执行 amis publish2oss --name=xxCmp

特别说明

此发布方式只是将自定义组件构建产物发布到 CDN 上，如要使用自定义组件还需要手动将其添加到平台运行时。

常见问题

Q1: 在 Windows VSCode 控制台执行 amis 相关命令出现报错
A: 如果提示“在此系统上禁止运行脚本”，这个可能是 Windows 客户端的默认安全策略影响，可尝试在控制台输入以下命令解决：

 Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

说明：以上命令用于设置允许当前用户在此 Windows 客户端执行所有脚本。关于 PowerShell 执行策略

项目工程配置说明（amis.config.js）

amis-cmp-cli 默认提供完整配置；如需自定义，使用 amis config init 生成 amis.config.js 并按需修改。

以下为常用配置示例（片段可自由组合）。

1) 代码规范与检查相关配置

module.exports = {
  settings: {
    enableESLint: true, // 是否开启ESLint，默认开启ESLint检测代码格式
    enableESLintFix: false, // 是否ESLint自动修正代码格式
    enableStyleLint: true, // 是否开启StyleLint，默认开启ESLint检测代码格式
    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
  },
}

2) 构建入口配置（优先级：linkDebug/build2lib/publish2oss.entry > webpack.entry）

【提示】当未配置 entry 时，cli 默认从 src/components 目录下扫描并识别自定义组件，并自动生成对应的 entry 构建入口配置。

如需自定义构建入口配置，请按如下结构调整项目工程配置文件（amis.config.js）：

module.exports = {
  webpack: {
    entry: { index: './src/index.js' },
  },
  linkDebug: { entry: {} },
  build2lib: { entry: {} },
  publish2oss: { entry: {} },
}

备注: 详细配置方法请查看 Webpack 官网 (关于entry的配置方法)。

3) 解析配置（extensions/alias）

module.exports = {
  webpack: {
    resolve: {
      extensions: ['.js', '.jsx', '.vue', 'json'],
      alias: {},
    },
  },
}

备注1: extensions 的详细配置方法请查看Webpack官网 (关于resolve-extensions的配置方法)；
备注2: alias 的详细配置方法请查看 Webpack 官网 (关于resolve-alias的配置方法)。

4) 页面模板与公共样式资源

module.exports = {
  webpack: {
    template: '', // 自定义页面模板路径
    sassResources: [], // sassResources 中添加的 样式文件会作为项目的公共SASS内容（变量、mixin、function等）
  },
}

5) 依赖打包策略（忽略 node_modules）

module.exports = {
  webpack: {
    ignoreNodeModules: true, // 打包时是否忽略 node_modules，默认为false
    allowList: [], // 用于配置会注入bundle中的依赖包（ignoreNodeModules 为 true 时生效）
  },
}

6) TypeScript 声明文件与工程目录

module.exports = {
  webpack: {
    createDeclaration: false, // 可选择是否生成ts声明文件，默认为false
    projectDir: ['./src'], // 构建项目中，设置生效的目录（可同时设置多个目录），用于提高前端工程执行效率。可以不配置，默认为['./src']
  },
}

7) 环境变量替换（params-replace-loader）

module.exports = {
  envParams: {
    common: { '#version#': '20250822.1' },
    local: {
      '#dataApiBase#': 'http://localhost:1024',
      '#assetsPublicPath#': 'http://localhost:1024',
      '#routeBasePath#': '/',
    },
  },
}

8) 本地开发代理与 HTTPS

module.exports = {
  preview: {
    proxyTable: {},
    https: false,
  },
}

备注1: 关于proxyTable的配置方法；
备注2: 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 chrome://flags/#allow-insecure-localhost 并设置为 Enabled。

9) 库构建（UMD/ESM）

module.exports = {
  build2lib: {
    NODE_ENV: 'production',
    libraryName: '',
    assetsRoot: resolve('dist'),
    assetsPublicPath: '/',
    assetsSubDirectory: '',
    productionSourceMap: false,
    productionGzip: false,
    productionGzipExtensions: ['js', 'css', 'json'],
    bundleAnalyzerReport: false,
    ignoreNodeModules: true,
    allowList: [],
  },
}

10) 自定义 Loader / Plugin / Babel Plugins

module.exports = {
  webpack: {
    moduleRules: [], // 用于添加自定义 loaders
    plugins: [], // 用于添加自定义 plugins
    babelPlugins: [  // 用于添加自定义 Babel plugins
      [
        'component',
        { libraryName: 'element-ui', styleLibraryName: 'theme-chalk' },
      ],
    ],
  },
}

备注: 以上自定义 babelPlugins 用于实现 element-ui 组件按需引入。

也支持以函数形式动态调整内置 Babel Plugins：

module.exports = {
  webpack: {
    babelPlugins: (curBabelPlugins) => {
      curBabelPlugins.push(/* your plugin */)
      return curBabelPlugins
    },
  },
}

11) 自定义组件之间实现模块共享

步骤1：在自定义组件A（cmpType:amis-custom-cmpA）/ 配置文件（amis.config.js）中定义要共享出来的模块A（xxModule_A）

module.exports = {
  amisCommonModule: {
    // exports: ['xxModule'], // 数组写法，可用于导出自定义组件中的第三方依赖模块，
    exports: { 'xxModule_A': path.resolve('./src/components/xxModule_A') }, // 对象写法，可用于导出自定义组件中的某个内容模块（需要使用绝对路径导出）
  },
}

步骤2：在自定义组件B（cmpType:amis-custom-cmpB）/ 配置文件（amis.config.js）中声明需要使用自定义组件 A 分享出来的模块（xxModule_A）

module.exports = {
  amisCommonModule: {
    remoteDeps: ['amis-custom-cmpA'], // 远程依赖（自定义组件），表示当前自定义组件 B 会用到哪些自定义组件
    externals: ['xxModule_A'], // 自定义组件中需要剔除的外部模块（远程自定义组件中分享出来的模块），仅支持数组写法，需要和 remoteDeps 配合使用
  },
}

步骤3：在自定义组件B 中使用自定义组件 A 分享出来的模块（xxModule_A）

import xxModuleA from 'xxModule_A'; // 导入自定义组件 A 共享出来的模块

如需更多细节与高级用法，请参考模板项目与源码注释。