neo-cmp-cli 1.13.18 → 1.13.20

package/README.md

@@ -1,44 +1,45 @@
 # Neo 自定义组件开发工具
 
-neo-cmp-cli 是 Neo 自定义组件开发工具，基于 [AKFun](https://github.com/wibetter/akfun) 的工程能力，提供初始化、编译构建、预览调试、热更新、多技术栈支持和发布等功能。
+**neo-cmp-cli** 是面向 Neo 平台的自定义组件开发工具。它基于 [AKFun](https://github.com/wibetter/akfun) 的工程能力，提供项目初始化、编译构建、本地预览与热更新、多技术栈支持以及发布到 NeoCRM 等能力。
 
-## 📑 目录
+## 目录
 
 - [主要特性](#主要特性)
 - [内置模板](#内置模板)
 - [快速开始](#快速开始)
 - [命令参考](#命令参考)
-- [授权配置](#授权配置)
-- [开发指南](#开发指南)
-- [配置说明](#配置说明)
+- [CLI 常见问题](#cli-使用相关常见问题)
+- [登录与授权](#登录授权配置)
+- [组件开发说明](#组件开发说明)
+- [前端工程配置](#前端工程配置说明)
 
 ---
 
-## ✨ 主要特性
+## 主要特性
 
-- **零配置**: 内置默认配置（前端工程最佳实践），开箱可用
-- **多技术体系支持**: 支持 Vue2、React、React+TypeScript 多种技术栈类型自定义组件的调试、构建与发布
-- **多种构建类型**: 本地预览（含热更新/代理）、外链调试、库构建（UMD/ESM）、部署&发布
-- **灵活可配**: 支持构建入口、别名、代理、公共样式注入、ESLint/StyleLint、Babel/Loader/Plugin 扩展等配置
-- **样式与规范**: 内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint
-- **发布至 NeoCRM 平台**: 支持一键发布到 NeoCRM 平台的能力，需自行补充授权配置
+- **零配置**：内置符合前端工程实践的默认配置，开箱即用。
+- **多技术栈**：支持 Vue2、React、React + TypeScript 等类型的自定义组件调试、构建与发布。
+- **多种构建形态**：本地预览（含热更新与代理）、外链调试、库构建（UMD / ESM）、部署与发布。
+- **灵活可配**：可配置构建入口、路径别名、代理、公共样式注入、ESLint / StyleLint、以及 Babel / Loader / Plugin 等扩展。
+- **样式与规范**：内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint。
+- **对接 NeoCRM**：支持将组件发布到 NeoCRM 平台（需按文档完成授权配置）。
 
-## 📦 内置模板
+## 内置模板
 
-执行 `neo init` 时，CLI 会以列表展示可选模板；也可同时传入 `-t`（模板类型）与 `-n`（项目名称）跳过交互，直接从本仓库内置的 `template/` 目录初始化相应组件模板工程。
+执行 `neo init` 时，CLI 会以交互列表展示可选模板；若同时传入 `-t`（模板类型）与 `-n`（项目名称），可跳过交互，直接从本仓库 `template/` 目录初始化对应模板工程。
 
 | 模板类型 | 说明 | 参考仓库 |
-|-------------|------|----------|
-| `neo-web-entity-grid` | Web 端列表组件模板：含基础大列表、Picker 列表等示例组件 | （随 CLI 内置） |
-| `neo-h5-cmps` | H5 端业务组件模板：含全局搜索、数据列表、数据 Tabs、打开 AI 对话页等示例组件 | [neo-h5-cmps](https://github.com/wibetter/neo-h5-cmps) |
-| `neo` | 自定义业务组件模板：含实体表单、实体数据详情、实体数据表格等示例组件 | [neo-custom-cmp-template](https://github.com/wibetter/neo-custom-cmp-template) |
-| `neo-bi-cmps` | 数值指标组件模板: 可配置展示实体数据源中指标数据 | [neo-bi-cmps](https://github.com/xsy-neoui/neo-bi-cmps) |
-| `echarts` | ECharts 组件模板：含基于 ECharts 的图表示例组件（地图场景请使用 `amap` 模板） | [echarts-custom-cmp-template](https://github.com/wibetter/echarts-custom-cmp-template) |
+| --- | --- | --- |
+| `neo-web-entity-grid` | Web 端列表组件模板：含基础大列表、Picker 列表等示例 | （随 CLI 内置） |
+| `neo-h5-cmps` | H5 端业务组件模板：含全局搜索、数据列表、数据 Tabs、打开 AI 对话页等示例 | [neo-h5-cmps](https://github.com/wibetter/neo-h5-cmps) |
+| `neo` | 自定义业务组件模板：含实体表单、实体详情、实体数据表格等示例 | [neo-custom-cmp-template](https://github.com/wibetter/neo-custom-cmp-template) |
+| `neo-bi-cmps` | 数值指标组件模板：可配置展示实体数据源中的指标数据 | [neo-bi-cmps](https://github.com/xsy-neoui/neo-bi-cmps) |
+| `echarts` | ECharts 组件模板：含基于 ECharts 的图表示例（地图场景请使用 `amap` 模板） | [echarts-custom-cmp-template](https://github.com/wibetter/echarts-custom-cmp-template) |
 | `antd` | Ant Design 组件模板：含数据仪表板、搜索组件等示例 | [antd-custom-cmp-template](https://github.com/wibetter/antd-custom-cmp-template) |
-| `amap` | 地图组件模板：含基于高德地图 API 的示例组件 | [map-custom-cmp-template](https://github.com/wibetter/map-custom-cmp-template) |
+| `amap` | 地图组件模板：含基于高德地图 API 的示例 | [map-custom-cmp-template](https://github.com/wibetter/map-custom-cmp-template) |
 | `vue2` | Vue2 组件模板：含基于 Vue2 的示例组件 | [vue2-custom-cmp-template](https://github.com/wibetter/vue2-custom-cmp-template) |
 
-**非交互创建示例**（需同时提供 `-t` 与 `-n`）：
+**非交互创建**（须同时提供 `-t` 与 `-n`）示例：
 
 ```bash
 neo init -t neo-web-entity-grid -n myWebListCmp
@@ -50,27 +51,29 @@ neo init -t amap -n myMapCmp
 neo init -t vue2 -n myVue2Cmp
 ```
 
-> **说明**：本地拷贝模式（默认）下，`templateList` 中仍保留 `react-ts`、`react` 等目录时，可通过 `neo init -t react-ts -n xxx` 等方式创建，但已不再出现在上述交互列表中；`react`（非 TS）模板在 CLI 侧已标记为废弃，建议优先选用上表中的模板。
+> **说明**：在默认的本地拷贝模式下，若 `templateList` 中仍保留 `react-ts`、`react` 等目录，可通过 `neo init -t react-ts -n xxx` 等方式创建，但这些模板不会出现在上述交互列表中。`react`（非 TypeScript）模板在 CLI 侧已标记为废弃，建议优先选用上表中的模板。
 
 ---
 
-## 🚀 快速开始
+## 快速开始
 
 ### 1. 安装工具
 
 ```bash
-yarn global add neo-cmp-cli
+yarn global add neo-cmp-cli --registry https://registry.npmmirror.com
 # 或
-npm i -g neo-cmp-cli
+npm i -g neo-cmp-cli --registry=https://registry.npmmirror.com
 ```
 
+> **说明**：示例命令使用 [npmmirror](https://www.npmmirror.com/) 镜像，以加快安装速度；也可改用默认 npm 源。
+
 ### 2. 创建项目
 
 ```bash
 # 方式一：创建空的自定义组件项目
 neo create project
 
-# 方式二：根据模板创建自定义组件项目（交互选择模板；或 neo init -t <类型> -n <项目名称> 非交互）
+# 方式二：按模板创建（交互选择模板；或使用 neo init -t <类型> -n <名称> 非交互）
 neo init
 ```
 
@@ -90,710 +93,326 @@ yarn install
 neo create cmp
 ```
 
-默认在当前项目 `src/components/` 目录下新增自定义组件。
+默认在 `src/components/` 下新增自定义组件目录。
 
 ### 5. 本地预览
 
 ```bash
-# 预览自定义组件内容
 neo preview
 ```
 
-执行成功后，默认自动打开本地浏览器预览自定义组件内容。
+命令成功执行后，一般会默认打开浏览器进行预览。
 
-### 6. 外链调试（在 NeoCRM 端预览与调试）
+### 6. 外链调试（在 NeoCRM / 页面设计器中调试）
 
 ```bash
 neo linkDebug
 ```
 
-> **提示**：需在 NeoCRM / 页面设计器端启动 debug 模式，并添加控制台输出的外链脚本地址，方可在页面设计器端使用当前自定义组件。详细步骤请参考 [本地调试自定义组件](#本地调试自定义组件)。
+> **提示**：需在 NeoCRM 或页面设计器中开启 debug 模式，并将控制台输出的外链脚本地址加入「外部链接」。详细步骤见下文 [本地调试自定义组件](#2-本地调试自定义组件)。
 
-### 7. 发布到 NeoCRM 平台
+### 7. 发布到 NeoCRM
 
 ```bash
 neo push cmp
 ```
 
-> **提示**：发布前请确保 `package.json` 的 `name` 唯一、`version` 不重复，并已配置 NeoCRM 平台授权信息。详细说明请参考 [发布自定义组件至 NeoCRM](#发布自定义组件至-neocrm)。
+> **提示**：发布前请确认 `package.json` 中 `name` 在平台内唯一、`version` 未与已发布版本冲突，并完成 NeoCRM 授权配置。详见 [发布自定义组件至 NeoCRM](#3-发布自定义组件至-neocrm)。
 
 ---
 
-## 📋 命令参考
+## 命令参考
 
 | 命令 | 说明 | 参数 |
-|------|------|------|
-| `neo init` | 根据模板创建自定义组件项目 | `-t` / `--type` 模板类型（见 [内置模板](#内置模板)），`-n` / `--name` 项目名称；两者同时传入时为非交互 |
-| `neo create project` | 创建自定义组件空项目（不含任何自定义组件） | `--name` 指定项目名称 |
-| `neo create cmp` | 在当前项目中创建一个自定义组件 | `--name` 指定组件名称，`--targetDevice` / `-d` 指定项目类型 |
-| `neo login` | 登录 NeoCRM 平台（OAuth2 授权模式） | `-e` / `--env` 环境类型 |
-| `neo logout` | 登出 NeoCRM 平台 | - |
-| `neo preview` | 本地预览自定义组件内容，默认支持热更新与接口代理。（备注：当自定义组件使用 neo-ui-common 或者 neo-ui-component-web 时则不支持本地预览。） | `--name` 指定组件名称 |
-| `neo linkDebug` | 外链调试模式，在平台端页面设计器中调试自定义组件 | `--platform` 指定调试设备类型，`--name` 指定组件名称 |
-| `neo push cmp` | 构建并发布到 NeoCRM 平台 | `--name` 指定组件名称 |
-| `neo pull cmp` | 拉取线上自定义组件（NeoCRM 平台）至当前项目 | `--name` 指定组件名称 |
-| `neo delete cmp` | 删除线上自定义组件（NeoCRM 平台） | `--name` 指定组件名称 |
-
-## 常见问题
-
-**Q1: 在 Windows VSCode 控制台执行 neo 相关命令出现报错**  
-A: 如果提示“在此系统上禁止运行脚本”，这个可能是 Windows 客户端的默认安全策略影响，可尝试在控制台输入以下命令解决：
+| --- | --- | --- |
+| `neo init` | 按模板创建自定义组件项目 | `-t` / `--type` 模板类型（见 [内置模板](#内置模板)），`-n` / `--name` 项目名称；两者同时传入时为非交互模式 |
+| `neo create project` | 创建空项目（不含任何自定义组件） | `--name` 指定项目名称 |
+| `neo create cmp` | 在当前项目中创建一个自定义组件 | `--name` 组件名，`--targetDevice` / `-d` 指定目标设备类型 |
+| `neo login` | 登录 NeoCRM（OAuth2） | `-e` / `--env` 环境类型 |
+| `neo logout` | 登出 NeoCRM | — |
+| `neo preview` | 本地预览，默认支持热更新与接口代理。若组件依赖 `neo-ui-common` 或 `neo-ui-component-web`，则不支持本地预览 | `--name` 指定组件名 |
+| `neo linkDebug` | 外链调试，在页面设计器中调试自定义组件 | `--platform` 调试设备类型，`--name` 组件名 |
+| `neo push cmp` | 构建并发布到 NeoCRM | `--name` 组件名 |
+| `neo pull cmp` | 从 NeoCRM 拉取线上组件到当前项目 | `--name` 组件名 |
+| `neo delete cmp` | 删除 NeoCRM 上的指定自定义组件 | `--name` 组件名 |
 
-```bash
- Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
+## CLI 使用相关常见问题
+
+**Q1：在 Windows 的 VS Code 终端中执行 `neo` 相关命令报错**
+
+A：若提示「在此系统上禁止运行脚本」，多为 PowerShell 执行策略限制。可在当前用户范围放宽策略（需自行评估安全策略是否适用）：
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
 ```
 
-说明：以上命令用于设置 允许当前用户在此 Windows 客户端执行所有脚本。[关于 PowerShell 执行策略](https://learn.microsoft.com/zh-cn/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.5)
+> 说明：上述命令允许当前用户在 Windows 上执行脚本。更多背景见 Microsoft 文档：[about_Execution_Policies](https://learn.microsoft.com/zh-cn/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.5)。
 
+**Q2：提示「无法将“xxx”项识别为 cmdlet、函数、脚本文件或可运行程序的名称」**
+
+A：多为 **PATH** 未包含 npm 全局可执行文件目录。可按下面步骤将 npm 全局路径加入 PATH（PowerShell 示例）：
+
+**步骤 1**：查看 npm 全局前缀路径
+
+```powershell
+$npmPath = npm config get prefix
+```
+
+**步骤 2**：将路径加入当前会话的 PATH（立即生效）
+
+```powershell
+$env:PATH += ";$npmPath"
+```
+
+**步骤 3**：写入用户级环境变量（新开终端仍生效）
+
+```powershell
+[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")
+```
+
+> **说明**：若安装 Node.js 时未勾选安装必要工具等选项，也可能导致全局命令不可用；请结合本机安装方式排查。
 
 ---
 
-## 🔐 授权配置
+## 登录授权配置
 
-使用 `neo push cmp`、`neo pull cmp`、`neo delete cmp` 等命令与 NeoCRM 平台交互时，需要配置授权信息。
+使用 `neo push cmp`、`neo pull cmp`、`neo delete cmp` 等与 NeoCRM 交互前，需要完成授权。
 
-### 方式一：OAuth2 登录授权（推荐）
+### 方式一：OAuth2 登录（推荐）
 
-OAuth2 授权码模式更加安全可靠，无需用户配置账户名和密码。
+OAuth2 授权码模式无需在配置文件中保存账户密码，相对更安全。
 
 #### 使用步骤
 
-1. **登录 NeoCRM 平台**
+1. **登录 NeoCRM**
+
    ```bash
    neo login
    ```
-   
-   执行流程：
-   - 自动打开浏览器访问授权页面
-   - 在浏览器中输入 NeoCRM 账号密码进行登录（需选择对应的租户）
-   - 授权成功后自动跳转回本地（附带 code）
-   - cli 端 通过 code 获取 Token，并自动保存到项目的 `.neo-cli/token.json` 文件中
-
-2. **登出 NeoCRM 平台**
+
+   典型流程：
+
+   - 自动打开浏览器进入授权页；
+   - 在浏览器中登录 NeoCRM（需选择对应租户）；
+   - 授权成功后跳转回本地（携带 `code`）；
+   - CLI 用 `code` 换取 Token，并写入项目内 `.neo-cli/token.json`。
+
+2. **登出**
+
    ```bash
    neo logout
    ```
-   
-   功能：清除本地保存的 token 文件，下次使用需要重新登录。
 
-##### neo login 选择「自定义环境」时的授权配置示例
+   会清除本地保存的 token，下次使用需重新登录。
+
+##### 在 `neo login` 中选择「自定义环境」时的配置示例
 
 ```javascript
 // neo.config.js
 module.exports = {
   neoConfig: {
     neoBaseURL: 'https://crm-xx.xiaoshouyi.com', // 平台根地址（默认：https://crm.xiaoshouyi.com）
-    loginURL: 'https://login-xx.xiaoshouyi.com/auc/oauth2/auth', // 登录授权 URL（用于获取 code）
-    tokenAPI: 'https://login-xx.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址
+    loginURL: 'https://login-xx.xiaoshouyi.com/auc/oauth2/auth', // 授权页 URL（获取 code）
+    tokenAPI: 'https://login-xx.xiaoshouyi.com/auc/oauth2/token', // 换取 Token 的接口
   },
 }
 ```
 
 #### Token 有效期
 
-- **access_token**：默认有效期 2 小时
-- **refresh_token**：默认有效期 30 天
-- 系统会在 access_token 过期前 5 分钟自动刷新
-- 如果 refresh_token 也过期，需要重新执行 `neo login`
+- **access_token**：默认约 2 小时有效；
+- **refresh_token**：默认约 30 天有效；
+- 系统会在 access_token 过期前约 5 分钟尝试自动刷新；
+- 若 refresh_token 也过期，需重新执行 `neo login`。
+
+#### 授权登录常见问题
+
+**Q1：浏览器没有自动打开？**
+
+A：命令行会打印授权 URL，复制到浏览器中打开即可。
 
-#### 常见问题
+**Q2：Token 刷新失败？**
 
-**Q1: 浏览器无法自动打开怎么办？**  
-A: 命令行会输出授权 URL，手动复制到浏览器中打开即可。
+A：若 refresh_token 已过期，需重新执行 `neo login`；同时检查网络是否正常。
 
-**Q2: Token 刷新失败怎么办？**  
-A: 如果 refresh_token 也过期（默认 30 天），需要重新执行 `neo login`。同时检查网络连接是否正常。
+**Q3：登录后没有正确跳回 redirect_uri？**
 
-**Q3: 授权登录后没有正常跳回 redirect_uri**  
-A: 可能被浏览器安装的插件影响，目前已知会影响授权登录的浏览器插件有：Neo UI Extension，请关闭插件后重试。
+A：可能被浏览器扩展干扰；已知 **Neo UI Extension** 可能影响授权流程，可暂时关闭后重试。
 
-### 方式二：密码授权配置
+### 方式二：密码模式
 
-在项目根目录的 `neo.config.js` 文件中添加 NeoCRM 平台授权配置：
+在项目根目录 `neo.config.js` 中配置 NeoCRM 授权（示例）：
 
 ```javascript
 module.exports = {
   neoConfig: {
     neoBaseURL: 'https://crm-cd.xiaoshouyi.com', // 平台根地址（默认：https://crm.xiaoshouyi.com）
-    tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 获取接口地址
-    // NeoCRM 授权配置
+    tokenAPI: 'https://login-cd.xiaoshouyi.com/auc/oauth2/token', // Token 接口
     authType: 'password',
     auth: {
-      client_id: 'xx', // 客户端 ID，从创建连接器的客户端信息中获取（Client_Id）
-      client_secret: 'xxx', // 客户端秘钥，从创建连接器的客户端信息中获取（Client_Secret）
-      username: 'xx', // 用户在销售易系统中的用户名
+      client_id: 'xx', // 客户端 ID（连接器中的 Client_Id）
+      client_secret: 'xxx', // 客户端密钥（Client_Secret）
+      username: 'xx', // 销售易用户名
       /**
-       * password 为 用户在销售易系统中的账号密码加上 8 位安全令牌。
-       * 例如，用户密码为 123456，安全令牌为 ABCDEFGH，则 password 的值应为 123456ABCDEFGH。
+       * password 为「账户密码 + 8 位安全令牌」直接拼接（无空格）。
+       * 例如密码为 123456、安全令牌为 ABCDEFGH，则填 123456ABCDEFGH。
        */
-      password: 'xx xx' // 用户账户密码 + 8 位安全令牌
+      password: 'xxx', // 替换为实际「密码 + 安全令牌」
     },
   },
 }
 ```
 
-#### 授权配置获取方式
+#### 如何获取配置项
 
-1. **客户端 ID 和客户端秘钥**：需通过创建连接器获取
-   - 访问 [销售易文档中心](https://doc.xiaoshouyi.com) / 创建连接器
-   - 创建连接器后，从客户端信息中获取 `Client_Id` 和 `Client_Secret`
+1. **client_id / client_secret**  
+   通过「创建连接器」在客户端信息中获取 `Client_Id` 与 `Client_Secret`。可参考 [销售易文档中心](https://doc.xiaoshouyi.com) 中相关说明。
 
-2. **安全令牌**：如何获取安全令牌
-   - 访问 [销售易文档中心](https://doc.xiaoshouyi.com) / OAuth安全认证 / 密码模式 / 获取令牌
-   - 按照文档说明获取 8 位安全令牌
-   - `password` 字段 = 用户账户密码 + 8 位安全令牌（直接拼接，无空格或分隔符）
+2. **安全令牌与 password 字段**  
+   在文档中心 OAuth 相关章节（如密码模式、获取令牌）按说明获取 8 位安全令牌；`password` 一般为「登录密码 + 8 位安全令牌」直接拼接（无额外空格或分隔符，具体以官方文档为准）。
 
-### OAuth2 模式 vs 密码模式
+### OAuth2 与密码模式对比
 
 | 特性 | OAuth2 授权码模式 | 密码模式 |
-|------|------------------|---------|
-| 安全性 | ✅ 高（无需在配置文件中存储密码） | ⚠️ 较低（需要配置密码和安全令牌） |
-| Token 刷新 | ✅ 自动刷新 | ✅ 自动刷新 |
-| 有效期 | 2 小时（可自动刷新） | 永不过期 |
-| 推荐程度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
+| --- | --- | --- |
+| 安全性 | 较高（不在配置中存明文密码） | 较低（需配置密码与令牌） |
+| Token 刷新 | 支持自动刷新 | 支持自动刷新 |
+| 有效期 | access_token 约 2 小时（可刷新） | 视平台与 refresh 策略而定（见官方文档） |
+| 推荐程度 | 优先推荐 | 备选 |
 
 ---
 
-## 📖 开发指南
+## 组件开发说明
 
 ### 1. 默认自动识别自定义组件
 
-- **自动生成入口配置**：当 `entry` 未配置时，自动从 `src/components` 目录下扫描并识别自定义组件，`src/components` 下的子目录名称作为自定义组件的名称，并以其目录下的 `index.ts/.tsx/.js/.jsx` 文件作为组件内容文件，`model.[tj]s` 作为模型内容文件
-- **自动注册自定义组件**：当 `entry` 未配置时，自动生成自定义组件注册文件和模型注册文件，并注入到构建脚本中，无需用户手动编写注册文件（[neo-register](https://www.npmjs.com/package/neo-register)）
-- **构建时自动增加样式隔离**：发布和 linkDebug 调试自定义组件时会自动给组件增加样式隔离（默认处理组件目录下的 (index|style).(scss|less) 样式文件），避免影响 Neo 平台样式。此模式对自定义组件根节点的样式命名有一定的规范要求（需要和组件名称保持一致），不符合规范会导致根节点样式失效。如需关闭此功能，请在 neo.config.js / webpack 中将 disableAutoAddStyleScope 设置为 true。
-
-### 2. 设置自定义组件属性配置项
-
-通过 `neo init` 初始化的自定义组件，默认自带组件模型文件，所有和页面设计器关联的信息均在此文件中定义（详细见 model 文件中的注释说明）。
-
-自定义组件模型文件中可以设置的属性：
-
-| 属性名 |    默认值     |      使用说明      |
-|-------|------------------|---------------|
-| cmpType | 在构建时根据当前组件目录名称自动生成 | 组件类型标识，用于标识组件的唯一性 |
-| label | - | 组件名称，用于设置在编辑器左侧组件面板中展示的名称 |
-| description | - | 组件描述，用于设置在编辑器左侧组件面板中展示的描述 |
-| iconUrl | - | 组件图标，用于设置在编辑器左侧组件面板中展示的图标  |
-| tags | ['自定义组件'] | 分类标签，用于设置在编辑器左侧组件面板哪个分类中展示 |
-| exposedToDesigner | true | 是否在页面设计器端可见  |
-| enableDuplicate | true | 在设计器中是否允许多次使用  |
-| targetPage | ['all'] | 适配的页面类型  |
-| targetObject | ['all'] | 支持的实体类型  |
-| targetApplication | ['all'] | 支持的应用类型  |
-| targetDevice | 'all' | 支持的设备类型  |
-| defaultComProps | - | 初次插入页面的默认属性数据 |
-| propsSchema | - | 定义组件在编辑器中可配置的属性 |
-
-说明1：其中 `propsSchema` 用于添加自定义组件的属性配置面板，可用的配置项类型请见 [neo-register 使用文档](https://www.npmjs.com/package/neo-register)。
-
-说明2：当前 NeoCRM 平台存在的页面类型：
-- all: 所有页面类型
-- indexPage: 首页
-- entityListPage:	实体列表页
-- entityFormPage:	实体表单页
-- entityDetailPage:	实体详情页
-- customPage:	自定义页面
-- bizPage: 业务页面
-
-### 3. 使用平台实体数据源
-
-可在自定义组件中使用 OpenAPI SDK 对接平台实体数据源，详细使用方法见 [neo-open-api](https://www.npmjs.com/package/neo-open-api)。
-
-```typescript
-import { xObject } from 'neo-open-api';
-
-// 查询联系人列表
-const {data: contacts} = await xObject.query({
-  xObjectApiKey: 'Contact',
-  fields: ['name', 'phone', 'email'],
-  page: 1,
-  pageSize: 20,
-  orderBy: 'createdAt desc'
-});
-
-// 创建新联系人
-const {data: newContact} = await xObject.create('Contact', {
-  data: {
-    name: '王五',
-    phone: '13700137000',
-    email: 'wangwu@example.com'
-  }
-});
-
-// 更新联系人
-const {data: updatedContact} = await xObject.update('Contact', newContact.id, {
-  data: {
-    name: '王五（更新）'
-  }
-});
-
-// 获取联系人详情
-const {data: contactDetail} = await xObject.get('Contact', newContact.id);
-
-// 删除联系人
-await xObject.delete('Contact', newContact.id);
-```
-
-
-### 4. 使用平台自定义API
-
-可在自定义组件中使用 OpenAPI SDK 对接平台自定义API，详细使用方法见 [neo-open-api](https://www.npmjs.com/package/neo-open-api)。
-
-```typescript
-import { customApi } from 'neo-open-api';
-
-// 基本用法
-const result = await customApi.run({
-  apiUrl: '/rest/custom/api/endpoint', // 自定义API地址
-  methodType: 'POST', // 请求方法，如 'GET', 'POST', 'PUT', 'DELETE' 等（可选，默认为 'POST'）
-  data: { // 请求数据
-    key1: 'value1',
-    key2: 'value2'
-  }
-});
-```
-
-**参数说明：**
-- `apiUrl`: 自定义API的完整地址（必填）
-- `methodType` 或 `method`: 请求方法，默认为 'POST'
-- `data`: 请求数据对象，会被包装在 `data` 字段中发送
-
-**返回结果：**
-```typescript
-{
-  status: boolean, // 返回 true 表示执行成功
-  code: number | string, // 返回码
-  msg: string, // 一般用于返回错误信息
-  data: any // API返回的数据
-}
-```
-
-**使用示例：**
-```typescript
-import { customApi } from 'neo-open-api';
-
-// 执行自定义API
-const result = await customApi.run({
-  apiUrl: '/rest/custom/api/processData',
-  methodType: 'POST',
-  data: {
-    param1: 'value1',
-    param2: 'value2'
-  }
-});
-```
-
-### 5. 添加事件动作
-
-以下说明如何在自定义组件中添加 **可触发事件**、**可执行动作（组件函数）**，以及（不推荐）**广播事件**，以便在 Neo 页面设计器的属性面板 / 事件配置中完成事件与动作绑定。
-
-#### 添加可触发的组件事件
-
-**1. 在组件中添加可触发的事件**
-
-**步骤 1：** 从 `neo-ui-common` 导入 `NeoEvent`。
-
-> **备注：** 无需单独安装 `neo-ui-common`，组件在 Neo 平台运行时会自动注入。
-
-```typescript
-// 引入 neo-ui-common / NeoEvent
-// @ts-ignore
-import { NeoEvent } from 'neo-ui-common';
-```
-
-**步骤 2：** 使用 `@NeoEvent.dispatch` 将某个方法声明为可由设计器绑定的触发事件方法。
-
-```typescript
-/**
- * 表单提交事件
- */
-@NeoEvent.dispatch
-onSubmit() {
-  console.log('触发了表单提交事件：', this.props);
-}
-```
-
-**2. 在组件模型中声明会触发的事件**
-
-上述步骤仅在运行时定义了事件方法，页面设计器还不知道该组件对外暴露哪些事件，因此需要在 **组件模型**（如 `*Model` 描述类）中声明：
-
-```typescript
-/**
- * @file Object Form 表单组件对接编辑器的描述文件
- * @description 定义组件在 Neo 平台编辑器中的配置信息
- */
-export class EntityFormModel {
-  // ... 组件模型其他内容
-
-  /**
-   * 声明当前组件会触发的所有事件
-   * 备注：页面设计器端可用于进行事件绑定，在组件属性配置模式中配置事件动作
-   */
-  events = [
-    {
-      apiKey: 'onSubmit', // 事件名称（需与组件方法名一致）
-      label: '提交表单后', // 设计器中展示的名称
-      helpText: '表单提交后触发该事件', // 信息图标 hover 时的提示文本
-    },
-  ];
-}
-```
-
-**3. 发布自定义组件**
-
-发布后即可在页面设计器 / 属性配置面板中看到该组件可绑定的事件列表。
-
----
-
-#### 添加可执行的组件动作（组件函数）
-
-**1. 在组件中添加可执行的组件动作方法**
-
-**步骤 1：** 导入 `NeoEvent`（同上，无需安装 `neo-ui-common`）。
-
-```typescript
-// 引入 neo-ui-common / NeoEvent
-// @ts-ignore
-import { NeoEvent } from 'neo-ui-common';
-```
-
-**步骤 2：** 使用 `@NeoEvent.function` 将方法声明为可被其他组件或事件流调用的 **组件动作**。
-
-```typescript
-/**
- * 加载表格数据
- * @param page 页码，默认为 1
- * @param pageSize 每页条数，默认为 10
- */
-@NeoEvent.function
-async loadData(page = 1, pageSize = 10) {
-  const { xObjectApiKey } = this.props.xObjectDataApi || {};
-  if (!xObjectApiKey) return;
-
-  this.setState({ loading: true, error: null });
-
-  try {
-    const result = await xObject.query(this.props.xObjectDataApi);
-
-    if (result && result.status) {
-      const records = result.data || [];
-      const totalSize = result.totalSize || 0;
-
-      this.setState({
-        dataSource: records,
-        pagination: {
-          current: page,
-          pageSize,
-          total: totalSize,
-        },
-        loading: false,
-      });
-    } else {
-      this.setState({
-        error: result?.msg || '获取数据失败',
-        loading: false,
-      });
-    }
-  } catch (error: any) {
-    this.setState({
-      error: error.message || '获取数据失败',
-      loading: false,
-    });
-  }
-}
-```
-【备注】 如果组件方法中涉及 this 的使用，请在 constructor 构造函数中 将当前组件上下文绑定方法，确保组件方法在外部执行时this不丢失。（比如: this.loadData = this.loadData.bind(this)）
-
-> 示例中使用了 `xObject.query`，请确保已从 `neo-open-api` 引入 `xObject`，并与实际业务 props 一致。
+- **扫描与入口**：CLI 从 `src/components` 扫描子目录；子目录名为组件名；以目录下 `index.ts` / `tsx` / `js` / `jsx` 为组件入口，`model.ts` / `model.js` 为模型文件。
+- **自动注册**：发布时会生成注册相关文件并注入构建流程，一般无需手写注册代码（参见 [neo-register](https://www.npmjs.com/package/neo-register)）。
+- **样式隔离**：发布或 `linkDebug` 时会对组件样式做隔离处理（默认处理目录下 `(index|style).(scss|less)` 等）。根节点请使用**与组件目录名一致**的类名（className），避免被样式隔离策略影响。若需关闭，可在 `neo.config.js` 或 webpack 相关配置中将 `disableAutoAddStyleScope` 设为 `true`。
 
-**2. 在组件模型中声明可使用的组件函数**
+### 2. 本地调试自定义组件
 
-同样需要在模型中声明，设计器才能识别出可被调用的组件动作：
-
-```typescript
-/**
- * @file XObject 表格组件对接编辑器的描述文件
- * @description 定义组件在 Neo 平台编辑器中的配置信息
- */
-export class EntityFormModel {
-  // ... 组件模型其他内容
-
-  // 当前组件支持的函数列表（其他组件可触发当前组件的函数）
-  functions = [
-    {
-      apiKey: 'loadData',
-      label: '刷新表格',
-      helpTextKey: '刷新当前表格数据',
-    },
-    {
-      apiKey: 'handleDelete',
-      label: '删除记录',
-      helpTextKey: '删除表格中指定记录',
-      funcInParams: [
-        {
-          apiKey: 'id',
-          label: '记录ID',
-          type: 'String',
-          required: true,
-        },
-      ],
-    },
-  ];
-}
-```
-
-**3. 发布自定义组件**
-
-发布后在页面设计器 / 属性配置面板 / 事件配置面板中可看到并选用上述组件函数（组件动作）。
-
----
-
-#### 广播事件（不推荐使用）
-
-全局广播自由度高、难以追踪，请优先使用 **可触发事件 + 组件函数** 的声明式能力。
-
-**1. 在组件中触发广播事件**
-
-```typescript
-// @ts-ignore
-import { NeoEvent } from 'neo-ui-common';
-
-componentDidMount() {
-  // ... 其他代码
-  console.log('触发了一个广播事件 entityFormInit。');
-  NeoEvent.broadcast('entityFormInit', this.props);
-}
-```
-
-**2. 在组件中接收广播事件**
-
-```typescript
-// @ts-ignore
-import { NeoEvent } from 'neo-ui-common';
-
-componentDidMount() {
-  // ... 其他代码
-  NeoEvent.listen('entityFormInit', (eventData: any) => {
-    console.log('EntityCardList 监听到了广播事件 entityFormInit: ', eventData);
-    // ... 其他逻辑
-  });
-}
-```
-
-事件名在 `broadcast` 与 `listen` 中需保持一致。
-
-### 6. 默认复用平台第三方依赖
-
-自定义组件构建过程中默认会剔除掉平台已有依赖模块（比如 antd、echarts、axios、lodash 等），确保自定义组件构建后的资源体积较小。
-
-#### 平台预置的第三方依赖包
-
-自定义组件可直接使用以下第三方依赖包（NeoCRM 平台预置）：
-
-| 依赖包 | 版本 |
-|--------|------|
-| react | ^16.13.1 |
-| react-dom | ^16.13.1 |
-| mobx | ^6.3.0 |
-| mobx-react | ^7.0.0 |
-| mobx-state-tree | ^5.4.0 |
-| echarts | 5.4.2 |
-| antd | 4.9.4 |
-| antd-mobile | 2.3.4 |
-| @ant-design/icons | ^4.8.0 |
-| video-react | 0.14.1 |
-| axios | ^0.27.2 |
-| classnames | ^2.3.2 |
-| qs | ^6.11.0 |
-| lodash | ^4.17.21 |
-| neo-ui-component-web | ^1.0.0 |
-| neo-ui-common | ^1.0.0 |
-| neo-open-api | ^1.1.9 |
-| amis | ^1.1.5 |
-
-> **注意**：自定义组件中请使用依赖包支持的版本，如版本不匹配运行时可能出现异常。
-
-### 7. 本地调试自定义组件
-
-#### 步骤 1：启动外链调试模式
+#### 步骤 1：启动外链调试
 
 ```bash
 neo linkDebug
 ```
 
-启动成功后，当前命令控制台会输出一个可使用的外链脚本地址（通常为 `http://localhost:1024/index.js`）。
+成功后，终端会输出可使用的脚本地址（常见为 `http://localhost:1024/index.js`）。
 
-#### 步骤 2：登录 Neo 平台，打开页面设计器，并开启 debug 模式
+#### 步骤 2：在设计器中开启 debug
 
-在页面设计器 URL 后添加 `debug=true` 参数并重新访问，即可开启 debug 模式。
+在页面设计器 URL 后追加 `debug=true` 并重新访问。
 
-#### 步骤 3：添加外链脚本地址
+#### 步骤 3：添加外链脚本
 
-页面设计器开启 debug 模式后，左侧会展示**外部链接**管理面板。将第 1 步生成的「外链脚本地址」添加进来，即可在此页面设计器 / 组件物料面板中看到对应自定义组件。
+在设计器左侧「外部链接」面板中，将上一步输出的脚本地址加入，即可在物料中看到对应自定义组件。
 
-### 8. 发布自定义组件至 NeoCRM
+### 3. 发布自定义组件至 NeoCRM
 
-执行 `neo push cmp` 即可构建并发布自定义组件至 NeoCRM 平台，其构建后资源也会上传到 NeoCRM 平台端提供的 CDN 中。
+执行 `neo push cmp` 会构建组件并将资源发布到 NeoCRM（含平台 CDN 流程，以实际环境为准）。
 
-#### 使用方式
+#### 用法
 
 ```bash
-# 方式一：交互式选择要发布的自定义组件
+# 交互选择要发布的组件
 neo push cmp
 
-# 方式二：直接指定要发布的自定义组件名称
+# 指定组件名
 neo push cmp --name=xxCmp
 # 或
 neo push cmp -n xxCmp
 ```
 
-#### 发布前请确保
+#### 发布前检查
 
-- ✅ **package.json 的 name 唯一**：确保当前项目的 `package.json` 中的 `name` 字段在 NeoCRM 平台中唯一
-- ✅ **version 不重复**：每次发布时，请更新 `package.json` 中的 `version` 字段，确保版本号不重复
-- ✅ **已配置 NeoCRM 平台授权信息**：在 `neo.config.js` 中配置 `neoConfig.auth` 或使用 `neo login` 登录
-- ✅ **自定义组件已正确构建**：确保组件代码可以正常构建，且 `dist` 目录下有对应的构建产物
-- ✅ **组件模型文件存在**：确保组件目录下有 `model.ts` 或 `model.js` 文件，且正确导出了模型类
+- `package.json` 中 **`name`** 在 NeoCRM 中唯一；
+- **`version`** 与已发布版本不冲突（每次发布按需递增）；
+- 已完成 **NeoCRM 授权**（`neo.config.js` 或 `neo login`）；
+- 组件能 **正常构建**，`dist` 中有对应产物；
+- 组件目录存在 **`model.ts` 或 `model.js`**，且正确导出模型。
 
 #### 注意事项
 
-- **版本管理**：每次发布前务必更新 `package.json` 中的 `version` 字段，避免版本冲突
-- **组件名称唯一性**：确保 `package.json` 中的 `name` 字段在平台中唯一
-- **模型文件要求**：组件必须包含有效的模型文件（`model.ts` 或 `model.js`），且正确导出模型类
-- **技术栈一致性**：确保组件使用的技术栈与项目配置一致（React、React+TS、Vue2 等）
-- **构建产物完整性**：确保 `dist` 目录下包含组件的 JS 文件和模型文件（`xxCmp.js` 和 `xxCmpModel.js`）
-- **网络连接**：发布过程需要网络连接，确保可以访问 NeoCRM 平台和 OSS 服务
+- 发布前务必更新 `version`，避免冲突；
+- 组件名 / 包名在平台内需唯一；
+- 技术栈需与项目配置一致（React、React+TS、Vue2 等）；
+- 发布过程需稳定访问 NeoCRM 与对象存储等相关服务。
+
+#### 发布常见问题
 
-#### 常见问题
+**Q：提示「未找到 NeoCRM 平台授权配置」？**
 
-**Q: 发布失败，提示"未找到 NeoCRM 平台授权配置"**  
-A: 请检查 `neo.config.js` 文件中是否配置了 `neoConfig.auth`，或使用 `neo login` 进行 OAuth2 登录授权。
+A：检查 `neo.config.js` 是否配置 `neoConfig.auth`，或先执行 `neo login`。
 
-**Q: 发布失败，提示"未找到自定义组件模型文件"**  
-A: 请确保组件目录下有 `model.ts` 或 `model.js` 文件，且构建后在 `dist` 目录下生成了对应的 `xxCmpModel.js` 文件。
+**Q：提示「未找到自定义组件模型文件」？**
 
-**Q: 发布失败，提示"获取 token 失败（授权配置错误）"**  
-A: 请检查 `neo.config.js` 文件中是否配置了 `neoConfig.auth`，确保所有授权字段都已正确填写。
+A：确认存在 `model.ts` / `model.js`，且构建产物中含对应的 `xxCmpModel.js`。
 
-#### 线上 NeoCRM 端使用
+**Q：提示「获取 token 失败（授权配置错误）」？**
 
-发布成功后，即可在对应租户环境下的页面设计器和表单设计器中使用此自定义组件。
+A：核对 `neo.config.js` 中授权字段是否完整、正确。
 
-### 9. 拉取线上自定义组件至本地项目
+#### 在 NeoCRM 中使用
 
-执行 `neo pull cmp` 即可从 NeoCRM 平台拉取自定义组件源码到当前项目。该命令会将线上自定义组件的源码下载并解析到当前项目的 `src/components` 目录下。
+发布成功后，可在对应租户下的页面设计器、表单设计器等环境中使用该组件。
 
-#### 使用方式
+### 4. 拉取线上组件到本地
+
+`neo pull cmp` 会从 NeoCRM 拉取组件源码到当前项目的 `src/components`。
 
 ```bash
-# 方式一：交互式选择要拉取的自定义组件
 neo pull cmp
-
-# 方式二：直接指定要拉取的自定义组件名称
 neo pull cmp --name=xxCmp
-# 或
 neo pull cmp -n xxCmp
 ```
 
-#### 拉取前请确保
-
-- ✅ **已配置 NeoCRM 平台授权信息**（`neo.config.js` 中的 `neoConfig.auth` 或使用 `neo login`）
-- ✅ **当前项目目录中不存在同名自定义组件**（`./src/components` 目录下）
-- ✅ **拉取的组件与当前项目技术栈一致**（React、React+TS、Vue2 等）
+**拉取前**：已完成授权；`./src/components` 下不存在同名目录；线上组件技术栈与当前项目一致。
 
-#### 注意事项
-
-- 拉取的自定义组件会覆盖本地同名组件，请谨慎操作
-- 如果组件源码中包含新增的依赖包，拉取完成后会提示执行 `npm install` 或 `yarn install`
-- zip 源文件会保留在 `.neo-cli/zip-source` 目录下，可手动删除
+**注意**：会覆盖本地同名目录；若有新依赖，拉取后按提示执行 `npm install` / `yarn install`；zip 等中间文件可能留在 `.neo-cli/zip-source`，可按需清理。
 
-### 10. 删除线上自定义组件
+### 5. 删除线上自定义组件
 
-执行 `neo delete cmp` 即可从 NeoCRM 平台删除指定的自定义组件。该命令会删除平台上的自定义组件，删除后该组件将无法在页面设计器和表单设计器中使用。
-
-#### 使用方式
+`neo delete cmp` 会从 NeoCRM **删除**指定组件，删除后设计器中无法再选用（请谨慎操作）。
 
 ```bash
-# 方式一：交互式选择要删除的自定义组件
 neo delete cmp
-
-# 方式二：直接指定要删除的自定义组件名称
 neo delete cmp --name=xxCmp
-# 或
 neo delete cmp -n xxCmp
 ```
 
-#### 删除前请确保
-
-- ✅ **已配置 NeoCRM 平台授权信息**（`neo.config.js` 中的 `neoConfig.auth` 或使用 `neo login`）
-- ✅ **确认要删除的组件名称正确**，删除操作不可恢复
-
-#### 注意事项
-
-- ⚠️ **删除操作不可恢复**：删除后的自定义组件将无法恢复，请谨慎操作
-- ⚠️ **影响范围**：删除组件后，所有使用该组件的页面和表单将受到影响，请确保没有正在使用的场景
-- 💡 **建议先备份**：删除前建议先使用 `neo pull cmp` 拉取组件源码到本地进行备份
-
-### 11. 自定义组件之间实现模块共享
-
-**步骤 1**：在自定义组件A（customCmpA）/ 配置文件中定义要共享出来的模块A（xxModuleA）
-
-```javascript
-// customCmpA 组件的 neo.config.js
-module.exports = {
-  neoCommonModule: {
-    // exports: ['xxModule'], // 数组写法，用于导出当前自定义组件中的第三方依赖模块
-    exports: { 'xxModuleA': path.resolve('./src/components/xxModuleA') }, // 对象写法，可用于导出自定义组件中的某个内容模块（需要使用绝对路径导出）
-  },
-}
-```
-
-**步骤 2**：在自定义组件B（customCmpB）/ 配置文件中声明需要使用自定义组件 A 分享出来的模块（xxModuleA）
-
-```javascript
-// customCmpB 组件的 neo.config.js
-module.exports = {
-  neoCommonModule: {
-    remoteDeps: ['customCmpA'], // 远程依赖（自定义组件），表示当前自定义组件 B 会用到哪些自定义组件
-    externals: ['xxModuleA'], // 自定义组件中需要剔除的外部模块（远程自定义组件中分享出来的模块），仅支持数组写法，需要和 remoteDeps 配合使用
-  },
-}
-```
-
-**步骤 3**：在自定义组件B 中使用自定义组件 A 分享出来的模块（xxModuleA）
+**删除前**：已完成授权；再次确认组件名。**删除不可恢复**，且会影响已引用该组件的页面 / 表单；建议必要时先用 `neo pull cmp` 备份源码。
 
-```javascript
-import xxModuleA from 'xxModuleA'; // 导入自定义组件 A 共享出来的模块
-```
+---
 
-## ⚙️ 配置说明
+## 前端工程配置说明
 
-neo-cmp-cli 默认提供完整配置；如需自定义，使用 `neo config init` 生成 `neo.config.js` 并按需修改。
+neo-cmp-cli 内置一套完整默认配置；若需自定义，可执行 `neo config init` 生成 `neo.config.js` 后按需修改。
 
-以下为常用配置示例（片段可自由组合）。
+以下为常用配置片段（可按需组合）。
 
 ### 基础配置
 
-#### 1. 代码规范与检查相关配置
+#### 1. 代码规范（ESLint / StyleLint）
 
 ```javascript
 module.exports = {
   settings: {
-    enableESLint: true, // 是否开启ESLint，默认开启ESLint检测代码格式
-    enableESLintFix: false, // 是否ESLint自动修正代码格式
-    enableStyleLint: true, // 是否开启StyleLint，默认开启StyleLint检测代码格式
-    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
+    enableESLint: true, // 是否启用 ESLint
+    enableESLintFix: false, // 是否自动修复 ESLint 问题
+    enableStyleLint: true, // 是否启用 StyleLint
+    enableStyleLintFix: false, // 是否自动修复 StyleLint 问题
   },
 }
 ```
 
-#### 2. 构建入口配置
+#### 2. 构建入口
 
-> **提示**：当未配置 `entry` 时，cli 默认从 `src/components` 目录下扫描并识别自定义组件，并自动生成对应的 entry 构建入口配置。
+> **提示**：未配置 `entry` 时，CLI 默认扫描 `src/components` 并生成各组件的 entry。
 
-优先级：`linkDebug/build2lib/pushCmp.entry` > `webpack.entry`
+优先级：`linkDebug` / `build2lib` / `pushCmp` 的 `entry` > `webpack.entry`。
 
-如需自定义构建入口配置，请按如下结构调整项目工程配置文件（`neo.config.js`）：
+自定义示例：
 
 ```javascript
 module.exports = {
@@ -806,56 +425,55 @@ module.exports = {
 }
 ```
 
-> **备注**：详细配置方法请查看 Webpack 官网 [关于entry的配置方法](https://www.webpackjs.com/configuration/entry-context/#entry)。
+> 更多说明见 Webpack 文档：[entry](https://www.webpackjs.com/configuration/entry-context/#entry)。
 
-#### 3. 解析配置（extensions/alias）
+#### 3. 解析（extensions / alias）
 
 ```javascript
 module.exports = {
   webpack: {
     resolve: {
-      extensions: ['.js', '.jsx', '.vue', 'json'],
+      extensions: ['.js', '.jsx', '.vue', '.json'],
       alias: {},
     },
   },
 }
 ```
 
-> **备注**：
-> - extensions 的详细配置方法请查看 Webpack 官网 [关于resolve-extensions的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-extensions)
-> - alias 的详细配置方法请查看 Webpack 官网 [关于resolve-alias的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-alias)
+> - [resolve.extensions](https://www.webpackjs.com/configuration/resolve/#resolve-extensions)  
+> - [resolve.alias](https://www.webpackjs.com/configuration/resolve/#resolve-alias)
 
-#### 4. 页面模板与公共样式资源
+#### 4. 页面模板与公共样式
 
 ```javascript
 module.exports = {
   webpack: {
-    template: '', // 自定义页面模板路径
-    sassResources: [], // sassResources 中添加的 样式文件会作为项目的公共SASS内容（变量、mixin、function等）
+    template: '', // 自定义 HTML 模板路径
+    sassResources: [], // 作为全局注入的 Sass 资源（变量、mixin 等）
   },
 }
 ```
 
 ### 高级配置
 
-#### 5. 依赖打包策略（忽略 node_modules）
+#### 5. 依赖打包策略（ignoreNodeModules）
 
 ```javascript
 module.exports = {
   webpack: {
-    ignoreNodeModules: true, // 打包时是否忽略 node_modules，默认为false
-    allowList: [], // 用于配置会注入bundle中的依赖包（ignoreNodeModules 为 true 时生效）
+    ignoreNodeModules: true, // 是否忽略 node_modules（默认 false）
+    allowList: [], // ignoreNodeModules 为 true 时仍打入 bundle 的包
   },
 }
 ```
 
-#### 6. TypeScript 声明文件与工程目录
+#### 6. TypeScript 声明与扫描目录
 
 ```javascript
 module.exports = {
   webpack: {
-    createDeclaration: false, // 可选择是否生成ts声明文件，默认为false
-    projectDir: ['./src'], // 构建项目中，设置生效的目录（可同时设置多个目录），用于提高前端工程执行效率。可以不配置，默认为['./src']
+    createDeclaration: false, // 是否生成 .d.ts
+    projectDir: ['./src'], // 生效目录，可多个；默认 ['./src']
   },
 }
 ```
@@ -875,7 +493,7 @@ module.exports = {
 }
 ```
 
-#### 8. 本地开发代理与 HTTPS
+#### 8. 本地预览代理与 HTTPS
 
 ```javascript
 module.exports = {
@@ -886,11 +504,10 @@ module.exports = {
 }
 ```
 
-> **备注**：
-> - [关于proxyTable的配置方法](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy)
-> - 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 `chrome://flags/#allow-insecure-localhost` 并设置为 Enabled
+> - [devServer.proxy](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy)  
+> - 启用 HTTPS 后若浏览器提示不安全，可在 Chrome 中打开 `chrome://flags/#allow-insecure-localhost` 并启用对应选项（以浏览器版本为准）。
 
-#### 9. 库构建（UMD/ESM）
+#### 9. 库构建（UMD / ESM）
 
 ```javascript
 module.exports = {
@@ -910,14 +527,14 @@ module.exports = {
 }
 ```
 
-#### 10. 自定义 Loader / Plugin / Babel Plugins
+#### 10. 自定义 Loader / Plugin / Babel 插件
 
 ```javascript
 module.exports = {
   webpack: {
-    moduleRules: [], // 用于添加自定义 loaders
-    plugins: [], // 用于添加自定义 plugins
-    babelPlugins: [  // 用于添加自定义 Babel plugins
+    moduleRules: [],
+    plugins: [],
+    babelPlugins: [
       [
         'component',
         { libraryName: 'element-ui', styleLibraryName: 'theme-chalk' },
@@ -927,9 +544,9 @@ module.exports = {
 }
 ```
 
-> **备注**：以上自定义 babelPlugins 用于实现 [element-ui 组件按需引入](https://element.eleme.cn/#/zh-CN/component/quickstart#an-xu-yin-ru)。
+> 上例常用于 [Element UI 按需引入](https://element.eleme.cn/#/zh-CN/component/quickstart#an-xu-yin-ru)。
 
-也支持以函数形式动态调整内置 Babel Plugins：
+也支持用函数动态调整内置 Babel 插件列表：
 
 ```javascript
 module.exports = {
@@ -944,4 +561,4 @@ module.exports = {
 
 ---
 
-如需更多细节与高级用法，请参考模板项目与源码注释。
+更多细节请参考各模板项目与源码内注释。