neo-cmp-cli 1.7.3 → 1.7.5-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +355 -201
  2. package/package.json +7 -5
  3. package/src/config/auth.config.js +25 -0
  4. package/src/config/default.config.js +25 -0
  5. package/src/initData/neo.config.js +20 -11
  6. package/src/module/index.js +135 -93
  7. package/src/module/main.js +6 -5
  8. package/src/module/neoInitByCopy.js +4 -3
  9. package/src/neo/neoLogin.js +506 -0
  10. package/src/neo/neoService.js +98 -13
  11. package/src/template/antd-custom-cmp-template/neo.config.js +19 -10
  12. package/src/template/antd-custom-cmp-template/package.json +1 -1
  13. package/src/template/echarts-custom-cmp-template/neo.config.js +20 -11
  14. package/src/template/echarts-custom-cmp-template/package.json +1 -1
  15. package/src/template/empty-custom-cmp-template/neo.config.js +19 -10
  16. package/src/template/empty-custom-cmp-template/package.json +1 -1
  17. package/src/template/neo-custom-cmp-template/neo.config.js +15 -6
  18. package/src/template/neo-custom-cmp-template/package.json +1 -1
  19. package/src/template/react-custom-cmp-template/neo.config.js +19 -10
  20. package/src/template/react-custom-cmp-template/package.json +1 -1
  21. package/src/template/react-ts-custom-cmp-template/neo.config.js +19 -10
  22. package/src/template/react-ts-custom-cmp-template/package.json +1 -1
  23. package/src/template/vue2-custom-cmp-template/neo.config.js +19 -10
  24. package/src/template/vue2-custom-cmp-template/package.json +1 -1
  25. package/src/utils/cmpUtils/createCmpByZip.js +6 -0
  26. package/test/deprecate-versions.js +1 -1
package/README.md CHANGED
@@ -1,34 +1,56 @@
1
- ## Neo 自定义组件开发工具
2
- neo-cmp-cli 是 Neo 自定义组件开发工具，基于 [AKFun](https://github.com/wibetter/akfun) 的工程能力，提供 初始化、编译构建、预览调试、热更新、多技术栈支持和发布等功能。
3
-
4
- ### 主要特性
5
- - **零配置**: 内置默认配置，开箱可用；
6
- - **多技术栈**: 支持 Vue2、React、React+TypeScript 自定义组件的调试、构建与发布；
7
- - **多构建场景**: 本地预览（含热更新/代理）、外链调试、库构建（UMD/ESM）、部署&发布；
8
- - **灵活可配**: 支持 构建入口、别名、代理、SASS 注入、ESLint/StyleLint、Babel/Loader/Plugin 扩展等配置；
9
- - **样式与规范**: 内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint；
10
- - **发布至 CDN**: 内置发布到对象存储（OSS）的能力，支持自定义对象存储配置；
11
- - **发布至 NeoCRM 平台**: 支持一键发布到NeoCRM 平台的能力，需自行补充授权配置。
12
-
13
- ### 内置的自定义组件模板
14
- 创建自定义组件时（执行初始化命令 neo init）可选用。
15
- - **React + TS 模板**: [react-ts-custom-cmp-template](https://github.com/wibetter/react-ts-custom-cmp-template) 内置信息卡片列表展示组件示例
16
- - **React 模板(非 TS)**: [react-custom-cmp-template](https://github.com/wibetter/react-custom-cmp-template)
17
- - **Antd 模板**: [antd-custom-cmp-template](https://github.com/wibetter/antd-custom-cmp-template) 内置 Antd UI 组件实现的数据仪表板展示组件示例
18
- - **Neo 模板**: [neo-custom-cmp-template](https://github.com/wibetter/neo-custom-cmp-template) 支持使用平台实体数据源（内置平台实体数据对象的增删改查示例组件）
19
- - **Echarts 模板**: [echarts-custom-cmp-template](https://github.com/wibetter/echarts-custom-cmp-template) Echarts 图表自定义组件（含 高德地图展示组件示例）
20
- - **Vue2 模板**: [vue2-custom-cmp-template](https://github.com/wibetter/vue2-custom-cmp-template) Vue2.0 自定义组件
21
-
22
- ## 快速开始
23
-
24
- #### 1) 全局安装自定义组件开发工具
1
+ # Neo 自定义组件开发工具
2
+
3
+ neo-cmp-cli 是 Neo 自定义组件开发工具，基于 [AKFun](https://github.com/wibetter/akfun) 的工程能力，提供初始化、编译构建、预览调试、热更新、多技术栈支持和发布等功能。
4
+
5
+ ## 📑 目录
6
+
7
+ - [主要特性](#主要特性)
8
+ - [内置模板](#内置模板)
9
+ - [快速开始](#快速开始)
10
+ - [命令参考](#命令参考)
11
+ - [授权配置](#授权配置)
12
+ - [开发指南](#开发指南)
13
+ - [配置说明](#配置说明)
14
+
15
+ ---
16
+
17
+ ## ✨ 主要特性
18
+
19
+ - **零配置**: 内置默认配置，开箱可用
20
+ - **多技术栈**: 支持 Vue2、React、React+TypeScript 自定义组件的调试、构建与发布
21
+ - **多构建场景**: 本地预览（含热更新/代理）、外链调试、库构建（UMD/ESM）、部署&发布
22
+ - **灵活可配**: 支持构建入口、别名、代理、SASS 注入、ESLint/StyleLint、Babel/Loader/Plugin 扩展等配置
23
+ - **样式与规范**: 内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint
24
+ - **发布至 CDN**: 内置发布到对象存储（OSS）的能力，支持自定义对象存储配置
25
+ - **发布至 NeoCRM 平台**: 支持一键发布到 NeoCRM 平台的能力，需自行补充授权配置
26
+
27
+ ## 📦 内置模板
28
+
29
+ 创建自定义组件时（执行初始化命令 `neo init`）可选用以下模板：
30
+
31
+ | 模板名称 | 说明 | 链接 |
32
+ |---------|------|------|
33
+ | **React + TS** | 内置信息卡片列表展示组件示例 | [react-ts-custom-cmp-template](https://github.com/wibetter/react-ts-custom-cmp-template) |
34
+ | **React** | React 模板（非 TS） | [react-custom-cmp-template](https://github.com/wibetter/react-custom-cmp-template) |
35
+ | **Antd** | 内置 Antd UI 组件实现的数据仪表板展示组件示例 | [antd-custom-cmp-template](https://github.com/wibetter/antd-custom-cmp-template) |
36
+ | **Neo** | 支持使用平台实体数据源（内置平台实体数据对象的增删改查示例组件） | [neo-custom-cmp-template](https://github.com/wibetter/neo-custom-cmp-template) |
37
+ | **Echarts** | Echarts 图表自定义组件（含高德地图展示组件示例） | [echarts-custom-cmp-template](https://github.com/wibetter/echarts-custom-cmp-template) |
38
+ | **Vue2** | Vue2.0 自定义组件 | [vue2-custom-cmp-template](https://github.com/wibetter/vue2-custom-cmp-template) |
39
+
40
+ ---
41
+
42
+ ## 🚀 快速开始
43
+
44
+ ### 1. 安装工具
45
+
25
46
  ```bash
26
47
  yarn global add neo-cmp-cli
27
48
  # 或
28
49
  npm i -g neo-cmp-cli
29
50
  ```
30
51
 
31
- #### 2) 创建自定义组件项目
52
+ ### 2. 创建项目
53
+
32
54
  ```bash
33
55
  # 方式一：创建空的自定义组件项目
34
56
  neo create project
@@ -37,157 +59,148 @@ neo create project
37
59
  neo init
38
60
  ```
39
61
 
40
- #### 3) 进入自定义组件项目根目录，安装依赖并运行
62
+ ### 3. 进入项目并安装依赖
63
+
41
64
  ```bash
42
65
  cd xxCmpProject
66
+ npm install
67
+ # 或
68
+ yarn install
43
69
  ```
44
70
 
45
- #### 4) 创建自定义组件
71
+ ### 4. 创建自定义组件
72
+
46
73
  ```bash
47
74
  # 在当前项目中创建一个自定义组件
48
75
  neo create cmp
49
76
  ```
50
- 默认在当前项目 src/components/ 目录下新增自定义组件。
51
77
 
52
- #### 5) 本地预览自定义组件内容
78
+ 默认在当前项目 `src/components/` 目录下新增自定义组件。
79
+
80
+ ### 5. 本地预览
81
+
53
82
  ```bash
54
83
  # 预览自定义组件内容
55
84
  neo preview
56
85
  ```
86
+
57
87
  执行成功后，默认自动打开本地浏览器预览自定义组件内容。
58
88
 
59
- #### 6) 外链调试（在 NeoCRM 端预览与调试）
89
+ ### 6. 外链调试（在 NeoCRM 端预览与调试）
90
+
60
91
  ```bash
61
92
  neo linkDebug
62
93
  ```
63
- 需在NeoCRM / 页面设计器端启动 debug 模式，并添加控制台输出的外链脚本地址，方可在页面设计器端使用当前自定义组件。
64
94
 
65
- #### 7) 构建并发布到 NeoCRM
66
- 执行 `neo push cmp` 即可构建并发布自定义组件至 NeoCRM 平台。
67
- **发布前请确保**：`package.json` 的 `name` 唯一、`version` 不重复，并已配置 NeoCRM 平台授权信息。
95
+ > **提示**：需在 NeoCRM / 页面设计器端启动 debug 模式，并添加控制台输出的外链脚本地址，方可在页面设计器端使用当前自定义组件。详细步骤请参考 [本地调试自定义组件](#本地调试自定义组件)。
96
+
97
+ ### 7. 发布到 NeoCRM 平台
98
+
99
+ ```bash
100
+ neo push cmp
101
+ ```
102
+
103
+ > **提示**：发布前请确保 `package.json` 的 `name` 唯一、`version` 不重复，并已配置 NeoCRM 平台授权信息。详细说明请参考 [发布自定义组件至 NeoCRM](#发布自定义组件至-neocrm)。
104
+
105
+ ---
106
+
107
+ ## 📋 命令参考
108
+
109
+ | 命令 | 说明 | 参数 |
110
+ |------|------|------|
111
+ | `neo init` | 交互式创建自定义组件 | `-t` 指定模板，`--name` 指定组件名称 |
112
+ | `neo create project` | 创建自定义组件项目 | `--name` 指定项目名称 |
113
+ | `neo create cmp` | 在当前项目中创建一个自定义组件 | `--name` 指定组件名称 |
114
+ | `neo login` | 登录 NeoCRM 平台（OAuth2 授权模式） | - |
115
+ | `neo logout` | 登出 NeoCRM 平台 | - |
116
+ | `neo preview` | 本地预览自定义组件内容，默认支持热更新与接口代理 | `--name` 指定组件名称 |
117
+ | `neo linkDebug` | 外链调试模式，在平台端页面设计器中调试自定义组件 | `--name` 指定组件名称 |
118
+ | `neo publish2oss` | 构建并上传到对象存储 | `--name` 指定组件名称 |
119
+ | `neo push cmp` | 构建并发布到 NeoCRM 平台 | `--name` 指定组件名称 |
120
+ | `neo pull cmp` | 拉取线上自定义组件（NeoCRM 平台）至当前项目 | `--name` 指定组件名称 |
121
+ | `neo delete cmp` | 删除线上自定义组件（NeoCRM 平台） | `--name` 指定组件名称 |
122
+
123
+ ---
124
+
125
+ ## 🔐 授权配置
126
+
127
+ 使用 `neo push cmp`、`neo pull cmp`、`neo delete cmp` 等命令与 NeoCRM 平台交互时，需要配置授权信息。
128
+
129
+ ### 方式一：OAuth2 登录授权（推荐）
130
+
131
+ OAuth2 授权码模式更加安全可靠，且支持 token 自动刷新。
132
+
133
+ #### 使用步骤
134
+
135
+ 1. **登录 NeoCRM 平台**
136
+ ```bash
137
+ neo login
138
+ ```
139
+
140
+ 执行流程：
141
+ - 自动打开浏览器访问授权页面
142
+ - 在浏览器中输入 NeoCRM 账号密码进行登录
143
+ - 授权成功后自动跳转回本地
144
+ - Token 自动保存到项目的 `.neo-cli/token.json` 文件中
145
+
146
+ 2. **登出 NeoCRM 平台**
147
+ ```bash
148
+ neo logout
149
+ ```
150
+
151
+ 功能：清除本地保存的 token 文件，下次使用需要重新登录。
152
+
153
+ #### 配置示例
68
154
 
69
- ##### 需自行添加授权配置
70
155
  ```javascript
156
+ // neo.config.js
71
157
  module.exports = {
72
158
  neoConfig: {
73
159
  neoBaseURL: 'https://crm-cd.xiaoshouyi.com', // 平台根地址（默认：https://crm.xiaoshouyi.com）
74
- tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址（默认：https://login.xiaoshouyi.com/auc/oauth2/token）
75
- // NeoCRM 授权配置
76
- auth: {
77
- client_id: 'xx', // 客户端 ID，从创建连接器的客户端信息中获取（Client_Id）
78
- client_secret: 'xxx', // 客户端秘钥，从创建连接器的客户端信息中获取（Client_Secret）
79
- username: 'xx', // 用户在销售易系统中的用户名
80
- /**
81
- * password 为 用户在销售易系统中的账号密码加上 8 位安全令牌。
82
- * 例如，用户密码为 123456，安全令牌为 ABCDEFGH，则 password 的值应为 123456ABCDEFGH。
83
- */
84
- password: 'xx xx' // 用户账户密码 + 8 位安全令牌
85
- },
160
+ // 登录授权 URL（用于获取 code）
161
+ loginURL: 'https://login-cd.xiaoshouyi.com/auc/oauth2/auth',
162
+ tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址
86
163
  },
87
164
  }
88
165
  ```
89
- **详细使用说明**：请参考下方「[发布自定义组件至 NeoCRM](#6发布自定义组件至-neocrm)」章节。
90
-
91
- #### 8) 删除线上自定义组件
92
- 执行 `neo delete cmp` 即可从 NeoCRM 平台删除指定的自定义组件。
93
- **删除前请确保**：已配置 NeoCRM 平台授权信息，且确认要删除的组件名称正确（删除操作不可恢复）。
94
- **详细使用说明**：请参考下方「[删除线上自定义组件](#8删除线上自定义组件)」章节。
95
-
96
- ## 常用命令说明
97
- - **neo init**: 交互式创建自定义组件（支持 -t、--name）;
98
- - **neo create project**: 创建自定义组件项目（支持 --name）;
99
- - **neo create cmp**: 在当前项目中创建一个自定义组件（支持 --name）;
100
- - **neo preview**: 本地预览自定义组件内容（支持 --name），默认支持热更新与接口代理;
101
- - **neo linkDebug**: 外链调试模式，在平台端页面设计器中调试自定义组件;
102
- - **neo publish2oss**: 构建并上传到对象存储（支持 --name，可自定义配置对象存储）;
103
- - **neo push cmp**: 构建并发布到NeoCRM平台（支持 --name，需自行添加授权配置）；
104
- - **neo pull cmp**: 拉取线上自定义组件（NeoCRM平台）至当前项目（支持 --name，需自行添加授权配置）；
105
- - **neo delete cmp**: 删除线上自定义组件（NeoCRM平台）（支持 --name，需自行添加授权配置）。
106
-
107
- ## 开发须知
108
- #### 1）默认自动识别自定义组件
109
- - **自动生成入口配置**: 当 `entry` 未配置时，自动从 `src/components` 目录下扫描并识别自定义组件，`src/components` 下的子目录名称作为自定义组件的名称，并以其目录下的 `index.ts/.tsx/.js/.jsx` 文件作为组件内容文件，model.[tj]s 作为模型内容文件；
110
- - **自动注册自定义组件**: 当 `entry` 未配置时，自动生成自定义组件注册文件和模型注册文件，并注入到构建脚本中，无需用户手动编写注册文件（[neo-register](https://www.npmjs.com/package/neo-register)）。
111
-
112
- #### 2）设置自定义组件属性配置项
113
- 通过 neo init 初始化的自定义组件，默认自带组件模型文件，所有和页面设计器关联的信息均在此文件中定义（详细见 model 文件中的注释说明）。
114
- 其中 propsSchema 用于添加自定义组件的属性配置面板，当前可用的配置项类型请见 [neo-register 使用文档](https://www.npmjs.com/package/neo-register)。
115
-
116
- #### 3）在自定义组件使用平台实体数据源
117
- 可使用 OpenAPI SDK 对接平台实体数据源，详细使用方法见 [neo-open-api](https://www.npmjs.com/package/neo-open-api)。
118
166
 
119
- #### 4）默认复用平台第三方依赖
120
- 自定义组件构建过程中默认会剔除掉平台已有依赖模块（比如 antd、echarts、axios、lodash 等），确保自定义组件构建后的资源体积较小。
167
+ #### Token 有效期
121
168
 
122
- ##### 自定义组件可直接使用的第三方依赖包（NeoCRM 平台预置）：
123
- - react: '^16.13.1',
124
- - react-dom: '^16.13.1',
125
- - mobx: '^6.3.0',
126
- - mobx-react: '^7.0.0',
127
- - mobx-state-tree' '^5.4.0',
128
- - echarts: '5.4.2',
129
- - antd: '4.9.4',
130
- - antd-mobile: '2.3.4',
131
- - @ant-design/icons: '^4.8.0',
132
- - video-react: '0.14.1',
133
- - axios: '^0.27.2',
134
- - classnames: '^2.3.2',
135
- - qs: '^6.11.0',
136
- - lodash: '^4.17.21',
137
- - neo-ui-component-web: '^1.0.0',
138
- - neo-ui-common' '^1.0.0',
139
- - neo-open-api: '^1.0.11',
140
- - amis: '^1.1.5'
141
-
142
- 备注：自定义组件中请使用依赖包支持的版本，如版本不匹配运行时可能出现异常。
143
-
144
- #### 5）本地调试自定义组件
145
-
146
- ##### 1. 启动 外链调试模式
147
- ```
148
- neo linkDebug
149
- ```
150
- 启动成功后，当前命令控制台会输出一个可使用的 外链脚本地址（通常为 http://localhost:1024/index.js）。
169
+ - **access_token**：默认有效期 2 小时
170
+ - **refresh_token**：默认有效期 30 天
171
+ - 系统会在 access_token 过期前 5 分钟自动刷新
172
+ - 如果 refresh_token 也过期，需要重新执行 `neo login`
151
173
 
152
- ##### 2. 登录 Neo 平台，打开页面设计器，并开启 debug 模式
153
- 在页面设计器 URL 后添加 debug=true 参数并重新访问，即可开启 debug 模式
174
+ #### 常见问题
154
175
 
155
- ##### 3. 页面设计器开启 debug 模式后，左侧会展示 外部链接 管理面板
156
- 将第 1 步生成的「外链脚本地址」添加进来，即可在此页面设计器 / 组件物料面板中看到对应自定义组件。
176
+ **Q1: 浏览器无法自动打开怎么办？**
177
+ A: 命令行会输出授权 URL，手动复制到浏览器中打开即可。
157
178
 
158
- #### 6）发布自定义组件至 NeoCRM
159
- 执行 `neo push cmp` 即可构建并发布自定义组件至 NeoCRM 平台，其构建后资源也会上传到 NeoCRM 平台端提供的 CDN 中。
179
+ **Q2: Token 刷新失败怎么办？**
180
+ A: 如果 refresh_token 也过期（默认 30 天），需要重新执行 `neo login`。同时检查网络连接是否正常。
160
181
 
161
- ##### 使用方式
162
- ```bash
163
- # 方式一：交互式选择要发布的自定义组件
164
- neo push cmp
182
+ #### OAuth2 模式 vs 密码模式
165
183
 
166
- # 方式二：直接指定要发布的自定义组件名称
167
- neo push cmp --name=xxCmp
168
- # 或
169
- neo push cmp -n xxCmp
170
- ```
184
+ | 特性 | OAuth2 授权码模式 | 密码模式 |
185
+ |------|------------------|---------|
186
+ | 安全性 | ✅ 高（无需在配置文件中存储密码） | ⚠️ 较低（需要配置密码和安全令牌） |
187
+ | Token 刷新 | ✅ 自动刷新 | ✅ 自动刷新 |
188
+ | 有效期 | 2 小时（可自动刷新） | 2 小时（可自动刷新） |
189
+ | 推荐程度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
190
+
191
+ > **建议**：优先使用 OAuth2 授权码模式（`neo login`），更加安全便捷。
171
192
 
172
- ##### 发布前请确保
173
- - **package.json 的 name 唯一**：确保当前项目的 `package.json` 中的 `name` 字段在 NeoCRM 平台中唯一
174
- - **version 不重复**：每次发布时，请更新 `package.json` 中的 `version` 字段，确保版本号不重复
175
- - **已配置 NeoCRM 平台授权信息**：在 `neo.config.js` 中配置 `neoConfig.auth`
176
- - **自定义组件已正确构建**：确保组件代码可以正常构建，且 `dist` 目录下有对应的构建产物
177
- - **组件模型文件存在**：确保组件目录下有 `model.ts` 或 `model.js` 文件，且正确导出了模型类
193
+ ### 方式二：密码授权配置
178
194
 
179
- ##### 需自行添加授权配置
180
195
  在项目根目录的 `neo.config.js` 文件中添加 NeoCRM 平台授权配置：
196
+
181
197
  ```javascript
182
198
  module.exports = {
183
199
  neoConfig: {
184
200
  neoBaseURL: 'https://crm-cd.xiaoshouyi.com', // 平台根地址（默认：https://crm.xiaoshouyi.com）
185
- tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址（默认：https://login.xiaoshouyi.com/auc/oauth2/token）
201
+ tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址
186
202
  // NeoCRM 授权配置
187
203
  auth: {
188
- /**
189
- * 客户端 ID 和 客户端秘钥 需通过 创建连接器 获取
190
- */
191
204
  client_id: 'xx', // 客户端 ID，从创建连接器的客户端信息中获取（Client_Id）
192
205
  client_secret: 'xxx', // 客户端秘钥，从创建连接器的客户端信息中获取（Client_Secret）
193
206
  username: 'xx', // 用户在销售易系统中的用户名
@@ -201,16 +214,111 @@ module.exports = {
201
214
  }
202
215
  ```
203
216
 
204
- ##### 授权配置获取方式
217
+ #### 授权配置获取方式
218
+
205
219
  1. **客户端 ID 和客户端秘钥**：需通过创建连接器获取
206
220
  - 访问 [销售易文档中心](https://doc.xiaoshouyi.com) / 创建连接器
207
221
  - 创建连接器后，从客户端信息中获取 `Client_Id` 和 `Client_Secret`
222
+
208
223
  2. **安全令牌**：如何获取安全令牌
209
224
  - 访问 [销售易文档中心](https://doc.xiaoshouyi.com) / OAuth安全认证 / 密码模式 / 获取令牌
210
225
  - 按照文档说明获取 8 位安全令牌
211
226
  - `password` 字段 = 用户账户密码 + 8 位安全令牌（直接拼接，无空格或分隔符）
212
227
 
213
- ##### 注意事项
228
+ ---
229
+
230
+ ## 📖 开发指南
231
+
232
+ ### 1. 默认自动识别自定义组件
233
+
234
+ - **自动生成入口配置**：当 `entry` 未配置时，自动从 `src/components` 目录下扫描并识别自定义组件，`src/components` 下的子目录名称作为自定义组件的名称，并以其目录下的 `index.ts/.tsx/.js/.jsx` 文件作为组件内容文件，`model.[tj]s` 作为模型内容文件
235
+ - **自动注册自定义组件**：当 `entry` 未配置时，自动生成自定义组件注册文件和模型注册文件，并注入到构建脚本中，无需用户手动编写注册文件（[neo-register](https://www.npmjs.com/package/neo-register)）
236
+
237
+ ### 2. 设置自定义组件属性配置项
238
+
239
+ 通过 `neo init` 初始化的自定义组件，默认自带组件模型文件，所有和页面设计器关联的信息均在此文件中定义（详细见 model 文件中的注释说明）。
240
+
241
+ 其中 `propsSchema` 用于添加自定义组件的属性配置面板，当前可用的配置项类型请见 [neo-register 使用文档](https://www.npmjs.com/package/neo-register)。
242
+
243
+ ### 3. 使用平台实体数据源
244
+
245
+ 可使用 OpenAPI SDK 对接平台实体数据源，详细使用方法见 [neo-open-api](https://www.npmjs.com/package/neo-open-api)。
246
+
247
+ ### 4. 默认复用平台第三方依赖
248
+
249
+ 自定义组件构建过程中默认会剔除掉平台已有依赖模块（比如 antd、echarts、axios、lodash 等），确保自定义组件构建后的资源体积较小。
250
+
251
+ #### 平台预置的第三方依赖包
252
+
253
+ 自定义组件可直接使用以下第三方依赖包（NeoCRM 平台预置）：
254
+
255
+ | 依赖包 | 版本 |
256
+ |--------|------|
257
+ | react | ^16.13.1 |
258
+ | react-dom | ^16.13.1 |
259
+ | mobx | ^6.3.0 |
260
+ | mobx-react | ^7.0.0 |
261
+ | mobx-state-tree | ^5.4.0 |
262
+ | echarts | 5.4.2 |
263
+ | antd | 4.9.4 |
264
+ | antd-mobile | 2.3.4 |
265
+ | @ant-design/icons | ^4.8.0 |
266
+ | video-react | 0.14.1 |
267
+ | axios | ^0.27.2 |
268
+ | classnames | ^2.3.2 |
269
+ | qs | ^6.11.0 |
270
+ | lodash | ^4.17.21 |
271
+ | neo-ui-component-web | ^1.0.0 |
272
+ | neo-ui-common | ^1.0.0 |
273
+ | neo-open-api | ^1.0.11 |
274
+ | amis | ^1.1.5 |
275
+
276
+ > **注意**：自定义组件中请使用依赖包支持的版本，如版本不匹配运行时可能出现异常。
277
+
278
+ ### 5. 本地调试自定义组件
279
+
280
+ #### 步骤 1：启动外链调试模式
281
+
282
+ ```bash
283
+ neo linkDebug
284
+ ```
285
+
286
+ 启动成功后，当前命令控制台会输出一个可使用的外链脚本地址（通常为 `http://localhost:1024/index.js`）。
287
+
288
+ #### 步骤 2：登录 Neo 平台，打开页面设计器，并开启 debug 模式
289
+
290
+ 在页面设计器 URL 后添加 `debug=true` 参数并重新访问，即可开启 debug 模式。
291
+
292
+ #### 步骤 3：添加外链脚本地址
293
+
294
+ 页面设计器开启 debug 模式后，左侧会展示**外部链接**管理面板。将第 1 步生成的「外链脚本地址」添加进来，即可在此页面设计器 / 组件物料面板中看到对应自定义组件。
295
+
296
+ ### 6. 发布自定义组件至 NeoCRM
297
+
298
+ 执行 `neo push cmp` 即可构建并发布自定义组件至 NeoCRM 平台，其构建后资源也会上传到 NeoCRM 平台端提供的 CDN 中。
299
+
300
+ #### 使用方式
301
+
302
+ ```bash
303
+ # 方式一：交互式选择要发布的自定义组件
304
+ neo push cmp
305
+
306
+ # 方式二：直接指定要发布的自定义组件名称
307
+ neo push cmp --name=xxCmp
308
+ # 或
309
+ neo push cmp -n xxCmp
310
+ ```
311
+
312
+ #### 发布前请确保
313
+
314
+ - ✅ **package.json 的 name 唯一**：确保当前项目的 `package.json` 中的 `name` 字段在 NeoCRM 平台中唯一
315
+ - ✅ **version 不重复**：每次发布时，请更新 `package.json` 中的 `version` 字段，确保版本号不重复
316
+ - ✅ **已配置 NeoCRM 平台授权信息**：在 `neo.config.js` 中配置 `neoConfig.auth` 或使用 `neo login` 登录
317
+ - ✅ **自定义组件已正确构建**：确保组件代码可以正常构建，且 `dist` 目录下有对应的构建产物
318
+ - ✅ **组件模型文件存在**：确保组件目录下有 `model.ts` 或 `model.js` 文件，且正确导出了模型类
319
+
320
+ #### 注意事项
321
+
214
322
  - **版本管理**：每次发布前务必更新 `package.json` 中的 `version` 字段，避免版本冲突
215
323
  - **组件名称唯一性**：确保 `package.json` 中的 `name` 字段在平台中唯一
216
324
  - **模型文件要求**：组件必须包含有效的模型文件（`model.ts` 或 `model.js`），且正确导出模型类
@@ -218,10 +326,10 @@ module.exports = {
218
326
  - **构建产物完整性**：确保 `dist` 目录下包含组件的 JS 文件和模型文件（`xxCmp.js` 和 `xxCmpModel.js`）
219
327
  - **网络连接**：发布过程需要网络连接，确保可以访问 NeoCRM 平台和 OSS 服务
220
328
 
221
- ##### 常见问题
329
+ #### 常见问题
222
330
 
223
331
  **Q: 发布失败，提示"未找到 NeoCRM 平台授权配置"**
224
- A: 请检查 `neo.config.js` 文件中是否配置了 `neoConfig.auth`，确保所有授权字段都已正确填写。
332
+ A: 请检查 `neo.config.js` 文件中是否配置了 `neoConfig.auth`，或使用 `neo login` 进行 OAuth2 登录授权。
225
333
 
226
334
  **Q: 发布失败，提示"未找到自定义组件模型文件"**
227
335
  A: 请确保组件目录下有 `model.ts` 或 `model.js` 文件，且构建后在 `dist` 目录下生成了对应的 `xxCmpModel.js` 文件。
@@ -229,14 +337,16 @@ A: 请确保组件目录下有 `model.ts` 或 `model.js` 文件，且构建后
229
337
  **Q: 发布失败，提示"获取 token 失败（授权配置错误）"**
230
338
  A: 请检查 `neo.config.js` 文件中是否配置了 `neoConfig.auth`，确保所有授权字段都已正确填写。
231
339
 
232
- ##### 线上 NeoCRM 端使用
340
+ #### 线上 NeoCRM 端使用
341
+
233
342
  发布成功后，即可在对应租户环境下的页面设计器和表单设计器中使用此自定义组件。
234
343
 
235
- #### 7）拉取线上自定义组件至本地项目
236
- 执行 `neo pull cmp` 即可从 NeoCRM 平台拉取自定义组件源码到当前项目。
237
- 该命令会将线上自定义组件的源码下载并解析到当前项目的 `src/components` 目录下。
344
+ ### 7. 拉取线上自定义组件至本地项目
345
+
346
+ 执行 `neo pull cmp` 即可从 NeoCRM 平台拉取自定义组件源码到当前项目。该命令会将线上自定义组件的源码下载并解析到当前项目的 `src/components` 目录下。
347
+
348
+ #### 使用方式
238
349
 
239
- ##### 使用方式
240
350
  ```bash
241
351
  # 方式一：交互式选择要拉取的自定义组件
242
352
  neo pull cmp
@@ -247,21 +357,24 @@ neo pull cmp --name=xxCmp
247
357
  neo pull cmp -n xxCmp
248
358
  ```
249
359
 
250
- ##### 拉取前请确保
251
- - **已配置 NeoCRM 平台授权信息**（neo.config.js 中的 neoConfig.auth）
252
- - **当前项目目录中不存在同名自定义组件**（`./src/components` 目录下）
253
- - **拉取的组件与当前项目技术栈一致**（React、React+TS、Vue2 等）
360
+ #### 拉取前请确保
361
+
362
+ - ✅ **已配置 NeoCRM 平台授权信息**（`neo.config.js` 中的 `neoConfig.auth` 或使用 `neo login`）
363
+ - ✅ **当前项目目录中不存在同名自定义组件**（`./src/components` 目录下）
364
+ - ✅ **拉取的组件与当前项目技术栈一致**（React、React+TS、Vue2 等）
365
+
366
+ #### 注意事项
254
367
 
255
- ##### 注意事项
256
368
  - 拉取的自定义组件会覆盖本地同名组件，请谨慎操作
257
369
  - 如果组件源码中包含新增的依赖包，拉取完成后会提示执行 `npm install` 或 `yarn install`
258
370
  - zip 源文件会保留在 `.neo-cli/zip-source` 目录下，可手动删除
259
371
 
260
- #### 8）删除线上自定义组件
261
- 执行 `neo delete cmp` 即可从 NeoCRM 平台删除指定的自定义组件。
262
- 该命令会删除平台上的自定义组件，删除后该组件将无法在页面设计器和表单设计器中使用。
372
+ ### 8. 删除线上自定义组件
373
+
374
+ 执行 `neo delete cmp` 即可从 NeoCRM 平台删除指定的自定义组件。该命令会删除平台上的自定义组件，删除后该组件将无法在页面设计器和表单设计器中使用。
375
+
376
+ #### 使用方式
263
377
 
264
- ##### 使用方式
265
378
  ```bash
266
379
  # 方式一：交互式选择要删除的自定义组件
267
380
  neo delete cmp
@@ -272,25 +385,31 @@ neo delete cmp --name=xxCmp
272
385
  neo delete cmp -n xxCmp
273
386
  ```
274
387
 
275
- ##### 删除前请确保
276
- - **已配置 NeoCRM 平台授权信息**（neo.config.js 中的 neoConfig.auth）
277
- - **确认要删除的组件名称正确**，删除操作不可恢复
388
+ #### 删除前请确保
389
+
390
+ - ✅ **已配置 NeoCRM 平台授权信息**（`neo.config.js` 中的 `neoConfig.auth` 或使用 `neo login`）
391
+ - ✅ **确认要删除的组件名称正确**，删除操作不可恢复
392
+
393
+ #### 注意事项
394
+
395
+ - ⚠️ **删除操作不可恢复**：删除后的自定义组件将无法恢复，请谨慎操作
396
+ - ⚠️ **影响范围**：删除组件后，所有使用该组件的页面和表单将受到影响，请确保没有正在使用的场景
397
+ - 💡 **建议先备份**：删除前建议先使用 `neo pull cmp` 拉取组件源码到本地进行备份
278
398
 
279
- ##### 注意事项
280
- - **删除操作不可恢复**：删除后的自定义组件将无法恢复，请谨慎操作
281
- - **影响范围**：删除组件后，所有使用该组件的页面和表单将受到影响，请确保没有正在使用的场景
282
- - **建议先备份**：删除前建议先使用 `neo pull cmp` 拉取组件源码到本地进行备份
399
+ ### 9. 发布自定义组件至 CDN
283
400
 
284
- #### 9）发布自定义组件至CDN
285
- 执行 `neo publish2oss` 即可构建对应自定义组件，并自动将构建后资源上传到对象存储（OSS）中。
286
- 备注：请优先使用 neo push cmp。
401
+ 执行 `neo publish2oss` 即可构建对应自定义组件，并自动将构建后资源上传到对象存储（OSS）中。
287
402
 
288
- ##### 发布前请确保
289
- - **package.json 的 name 唯一**
290
- - **version 不重复**
291
- - 可按需配置对象存储参数（支持自定义），默认使用内置对象存储配置。
403
+ > **提示**：请优先使用 `neo push cmp` 发布到 NeoCRM 平台。
404
+
405
+ #### 发布前请确保
406
+
407
+ - ✅ **package.json 的 name 唯一**
408
+ - ✅ **version 不重复**
409
+ - ✅ 可按需配置对象存储参数（支持自定义），默认使用内置对象存储配置
410
+
411
+ #### 支持自定义对象存储配置
292
412
 
293
- ##### 支持自定义对象存储配置
294
413
  ```javascript
295
414
  module.exports = {
296
415
  publish2oss: {
@@ -310,34 +429,47 @@ module.exports = {
310
429
  }
311
430
  ```
312
431
 
313
- ##### 支持发布指定自定义组件
314
- 执行 `neo publish2oss --name=xxCmp`
432
+ #### 支持发布指定自定义组件
433
+
434
+ ```bash
435
+ neo publish2oss --name=xxCmp
436
+ ```
437
+
438
+ #### 特别说明
315
439
 
316
- ##### 特别说明
317
440
  此发布方式只是将自定义组件构建产物发布到 CDN 上，如要使用自定义组件还需要手动添加到指定租户上（NeoCRM 管理端 / 自定义组件管理页）。
318
441
 
319
- ## 项目工程配置说明（neo.config.js）
320
- neo-cmp-cli 默认提供完整配置；
321
- 如需自定义，使用 `neo config init` 生成 `neo.config.js` 并按需修改。
442
+ ---
443
+
444
+ ## ⚙️ 配置说明
445
+
446
+ neo-cmp-cli 默认提供完整配置；如需自定义，使用 `neo config init` 生成 `neo.config.js` 并按需修改。
322
447
 
323
448
  以下为常用配置示例（片段可自由组合）。
324
449
 
325
- ### 1) 代码规范与检查相关配置
450
+ ### 基础配置
451
+
452
+ #### 1. 代码规范与检查相关配置
453
+
326
454
  ```javascript
327
455
  module.exports = {
328
456
  settings: {
329
457
  enableESLint: true, // 是否开启ESLint，默认开启ESLint检测代码格式
330
458
  enableESLintFix: false, // 是否ESLint自动修正代码格式
331
- enableStyleLint: true, // 是否开启StyleLint，默认开启ESLint检测代码格式
459
+ enableStyleLint: true, // 是否开启StyleLint，默认开启StyleLint检测代码格式
332
460
  enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
333
461
  },
334
462
  }
335
463
  ```
336
464
 
337
- ### 2) 构建入口配置（优先级：linkDebug/build2lib/publish2oss.entry > webpack.entry）
338
- 【提示】当未配置 entry 时，cli 默认从 `src/components` 目录下扫描并识别自定义组件，并自动生成对应的 entry 构建入口配置。
465
+ #### 2. 构建入口配置
466
+
467
+ > **提示**：当未配置 `entry` 时，cli 默认从 `src/components` 目录下扫描并识别自定义组件，并自动生成对应的 entry 构建入口配置。
468
+
469
+ 优先级：`linkDebug/build2lib/publish2oss.entry` > `webpack.entry`
470
+
471
+ 如需自定义构建入口配置，请按如下结构调整项目工程配置文件（`neo.config.js`）：
339
472
 
340
- 如需自定义构建入口配置，请按如下结构调整项目工程配置文件（neo.config.js）：
341
473
  ```javascript
342
474
  module.exports = {
343
475
  webpack: {
@@ -348,9 +480,11 @@ module.exports = {
348
480
  publish2oss: { entry: {} },
349
481
  }
350
482
  ```
351
- 备注: 详细配置方法请查看 Webpack 官网 ([关于entry的配置方法](https://www.webpackjs.com/configuration/entry-context/#entry))。
352
483
 
353
- ### 3) 解析配置（extensions/alias）
484
+ > **备注**：详细配置方法请查看 Webpack 官网 [关于entry的配置方法](https://www.webpackjs.com/configuration/entry-context/#entry)。
485
+
486
+ #### 3. 解析配置（extensions/alias）
487
+
354
488
  ```javascript
355
489
  module.exports = {
356
490
  webpack: {
@@ -361,10 +495,13 @@ module.exports = {
361
495
  },
362
496
  }
363
497
  ```
364
- 备注1: extensions 的详细配置方法请查看Webpack官网 ([关于resolve-extensions的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-extensions))；
365
- 备注2: alias 的详细配置方法请查看 Webpack 官网 ([关于resolve-alias的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-alias))。
366
498
 
367
- ### 4) 页面模板与公共样式资源
499
+ > **备注**：
500
+ > - extensions 的详细配置方法请查看 Webpack 官网 [关于resolve-extensions的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-extensions)
501
+ > - alias 的详细配置方法请查看 Webpack 官网 [关于resolve-alias的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-alias)
502
+
503
+ #### 4. 页面模板与公共样式资源
504
+
368
505
  ```javascript
369
506
  module.exports = {
370
507
  webpack: {
@@ -374,7 +511,10 @@ module.exports = {
374
511
  }
375
512
  ```
376
513
 
377
- ### 5) 依赖打包策略（忽略 node_modules）
514
+ ### 高级配置
515
+
516
+ #### 5. 依赖打包策略（忽略 node_modules）
517
+
378
518
  ```javascript
379
519
  module.exports = {
380
520
  webpack: {
@@ -384,7 +524,8 @@ module.exports = {
384
524
  }
385
525
  ```
386
526
 
387
- ### 6) TypeScript 声明文件与工程目录
527
+ #### 6. TypeScript 声明文件与工程目录
528
+
388
529
  ```javascript
389
530
  module.exports = {
390
531
  webpack: {
@@ -394,7 +535,8 @@ module.exports = {
394
535
  }
395
536
  ```
396
537
 
397
- ### 7) 环境变量替换（params-replace-loader）
538
+ #### 7. 环境变量替换（params-replace-loader）
539
+
398
540
  ```javascript
399
541
  module.exports = {
400
542
  envParams: {
@@ -408,7 +550,8 @@ module.exports = {
408
550
  }
409
551
  ```
410
552
 
411
- ### 8) 本地开发代理与 HTTPS
553
+ #### 8. 本地开发代理与 HTTPS
554
+
412
555
  ```javascript
413
556
  module.exports = {
414
557
  preview: {
@@ -417,10 +560,13 @@ module.exports = {
417
560
  },
418
561
  }
419
562
  ```
420
- 备注1: [关于proxyTable的配置方法](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy)；
421
- 备注2: 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 `chrome://flags/#allow-insecure-localhost` 并设置为 Enabled。
422
563
 
423
- ### 9) 库构建（UMD/ESM）
564
+ > **备注**：
565
+ > - [关于proxyTable的配置方法](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy)
566
+ > - 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 `chrome://flags/#allow-insecure-localhost` 并设置为 Enabled
567
+
568
+ #### 9. 库构建（UMD/ESM）
569
+
424
570
  ```javascript
425
571
  module.exports = {
426
572
  build2lib: {
@@ -439,7 +585,8 @@ module.exports = {
439
585
  }
440
586
  ```
441
587
 
442
- ### 10) 自定义 Loader / Plugin / Babel Plugins
588
+ #### 10. 自定义 Loader / Plugin / Babel Plugins
589
+
443
590
  ```javascript
444
591
  module.exports = {
445
592
  webpack: {
@@ -454,9 +601,11 @@ module.exports = {
454
601
  },
455
602
  }
456
603
  ```
457
- 备注: 以上自定义 babelPlugins 用于实现 [element-ui 组件按需引入](https://element.eleme.cn/#/zh-CN/component/quickstart#an-xu-yin-ru)。
458
604
 
459
- 也支持以函数形式动态调整内置 Babel Plugins：
605
+ > **备注**：以上自定义 babelPlugins 用于实现 [element-ui 组件按需引入](https://element.eleme.cn/#/zh-CN/component/quickstart#an-xu-yin-ru)。
606
+
607
+ 也支持以函数形式动态调整内置 Babel Plugins：
608
+
460
609
  ```javascript
461
610
  module.exports = {
462
611
  webpack: {
@@ -468,33 +617,38 @@ module.exports = {
468
617
  }
469
618
  ```
470
619
 
471
- ### 11) 自定义组件之间实现模块共享
620
+ #### 11. 自定义组件之间实现模块共享
621
+
622
+ **步骤 1**：在自定义组件A（customCmpA）/ 配置文件中定义要共享出来的模块A（xxModuleA）
472
623
 
473
- 步骤1：在自定义组件A（cmpType:neo-custom-cmpA）/ 配置文件中定义要共享出来的模块A（xxModule_A）
474
624
  ```javascript
625
+ // customCmpA 组件的 neo.config.js
475
626
  module.exports = {
476
627
  neoCommonModule: {
477
628
  // exports: ['xxModule'], // 数组写法，用于导出当前自定义组件中的第三方依赖模块
478
- exports: { 'xxModule_A': path.resolve('./src/components/xxModule_A') }, // 对象写法，可用于导出自定义组件中的某个内容模块（需要使用绝对路径导出）
629
+ exports: { 'xxModuleA': path.resolve('./src/components/xxModuleA') }, // 对象写法，可用于导出自定义组件中的某个内容模块（需要使用绝对路径导出）
479
630
  },
480
631
  }
481
632
  ```
482
633
 
483
- 步骤2：在自定义组件B（cmpType:neo-custom-cmpB）/ 配置文件中 声明需要使用 自定义组件 A 分享出来的模块（xxModule_A）
634
+ **步骤 2**：在自定义组件B（customCmpB）/ 配置文件中声明需要使用自定义组件 A 分享出来的模块（xxModuleA）
635
+
484
636
  ```javascript
637
+ // customCmpB 组件的 neo.config.js
485
638
  module.exports = {
486
639
  neoCommonModule: {
487
- remoteDeps: ['neo-custom-cmpA'], // 远程依赖（自定义组件），表示当前自定义组件 B 会用到哪些自定义组件
488
- externals: ['xxModule_A'], // 自定义组件中需要剔除的外部模块（远程自定义组件中分享出来的模块），仅支持数组写法，需要和 remoteDeps 配合使用
640
+ remoteDeps: ['customCmpA'], // 远程依赖（自定义组件），表示当前自定义组件 B 会用到哪些自定义组件
641
+ externals: ['xxModuleA'], // 自定义组件中需要剔除的外部模块（远程自定义组件中分享出来的模块），仅支持数组写法，需要和 remoteDeps 配合使用
489
642
  },
490
643
  }
491
644
  ```
492
645
 
493
- 步骤3：在自定义组件B 源码中使用 自定义组件 A 分享出来的模块（xxModule_A）
646
+ **步骤 3**：在自定义组件B 中使用自定义组件 A 分享出来的模块（xxModuleA）
647
+
494
648
  ```javascript
495
- import ChartWidget from 'chart-widget'; // 导入自定义组件 A 共享出来的模块
649
+ import xxModuleA from 'xxModuleA'; // 导入自定义组件 A 共享出来的模块
496
650
  ```
497
651
 
498
-
499
652
  ---
653
+
500
654
  如需更多细节与高级用法，请参考模板项目与源码注释。