常见问题

本文汇总自定义组件开发、发布与设计器使用过程中较常遇到的问题及处理思路。

1. 在 Windows 控制台执行 neo 相关命令出现报错

如果提示「在此系统上禁止运行脚本」，可能是 Windows 客户端的默认安全策略影响，可尝试在控制台输入以下命令解决：

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

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

2. 在 Windows 控制台执行 neo 相关命令时，提示「无法将 xxx 项识别为 cmdlet、函数、脚本文件或可运行程序的名称」

该报错是 Windows 上典型的环境变量 PATH 问题，PowerShell 找不到已安装的 CLI 命令所在目录。可按以下三步将 npm 全局路径加入 PATH：

步骤 1：查看 npm 全局安装路径（自动获取）

$npmPath = npm config get prefix

步骤 2：把路径加到当前终端 PATH（立刻生效）

$env:PATH += ";$npmPath"

步骤 3：永久写入用户环境变量（重启后仍有效）

[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")

说明：出现以上问题时，常见原因是安装 Node 时未勾选安装向导中的相关工具选项（例如「Automatically install the necessary tools…」等）。

3. 发布时报错：找不到 neo-ui-common 模块

原因： neo-ui-common 是平台提供的虚拟模块（并非真实 NPM 包），仅在 Neo 平台运行时会自动注入。

解决方式一：使用 neo-cmp-cli

使用 neo-cmp-cli 构建并发布自定义组件。由 neo create project 或者 neo init 创建的项目默认以 neo-cmp-cli 作为构建工具，发布构建时会正确识别 neo-ui-common、neo-ui-component-web 等虚拟模块。

解决方式二：自建 Webpack 时用 externals 处理

若项目未使用 neo-cmp-cli、且用 Webpack 打包，可通过 externals 的函数形式将上述模块映射为运行时的 neoRequire：

// webpack.config.js
module.exports = {
  // 其他配置（entry、output、module 等）保持不变
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist',
  },
  externals: [
    // 1. 对象形式：处理固定映射的外部依赖（优先匹配）
    {
      // 原有的 externals 配置
    },
    // 2. 函数形式：兜底处理，将 neo-ui-common 等替换为 neoRequire（对象未匹配时执行）
    function (context, request, callback) {
      const neoModules = ['neo-ui-common'];
      if (neoModules.includes(request)) {
        return callback(null, `neoRequire("${request}")`, 'commonjs');
      }
      callback();
    },
  ],
};

说明： 上述「对象 + 函数」混写在 Webpack 5 中支持。Webpack 4 及以下不支持该数组混写形式；若需兼容低版本，请将对象规则并入函数内统一处理。

4. 发布后，设计器左侧组件面板看不到自定义组件

请依次排查：

1. 是否缺少模型文件： 自定义组件需在组件目录下提供模型脚本，例如 src/components/xx/model.[tj]s。
2. 模型中的页面/设备是否与当前设计器一致： 检查组件模型里的 targetPage、targetDevice 是否与当前打开的设计器类型匹配。

5. 拖拽到画布后未正常渲染（例如只显示空白）

可能原因： 组件运行时报错。

请打开浏览器开发者工具查看控制台，按报错信息修复组件逻辑或依赖问题。

6. 属性里「是否显示」设为「否」未生效

可能原因： 组件未使用 props.className。

说明： 设计器在隐藏组件时，会向 props.className 注入 design-hide，用于控制展示/隐藏。若组件根节点未把 className 合并到 DOM 上，则隐藏样式不会生效。

7. 事件动作「组件控制 / 组件可见行」未生效

可能原因： 组件未继承 BaseCmp。

「组件控制」「组件可见行」等能力依赖 BaseCmp，请确保自定义组件继承 BaseCmp。

8. 已配置的事件动作不执行

请依次排查：

1. 是否继承 BaseCmp： 组件模型中的 functions（可被其他组件调用的动作）依赖 BaseCmp。
2. this 是否丢失： 若组件函数内使用 this，请在构造函数中对组件函数进行上下文绑定，例如：this.refreshData = this.refreshData.bind(this)，确保执行事件动作时可以正常获取到组件上下文（this）。

9. 自定义组件根节点样式未生效

可能原因： 根节点没有使用与组件目录名一致的类名（className），被样式隔离策略影响。

组件根节点请使用与组件目录名一致的类名，避免被样式隔离策略影响。