从零到一：手把手教你用YonBuilder for NCC搭建NC Cloud 2021.11开发环境（含避坑指南）

从零到一：手把手教你用YonBuilder for NCC搭建NC Cloud 2021.11开发环境（含避坑指南）

在数字化转型浪潮中，企业级应用开发平台正经历着前所未有的技术迭代。作为用友网络推出的新一代企业云服务开发框架，NC Cloud（简称NCC）凭借其模块化架构和开放生态，已成为众多企业系统升级的首选方案。但对于初次接触NCC开发的工程师而言，从开发环境搭建到第一个功能模块的实现，往往需要跨越重重技术门槛。

本文将彻底解决这个痛点——我们将以2021.11版本为例，通过可视化操作+命令行调试双轨模式，完整演示如何从裸机开始构建可投入生产的NCC开发环境。不同于碎片化的技术文档，本指南特别强调三个核心价值：

1. 环境配置的原子化分解：每个步骤都附带验证方法，确保操作可逆且结果可验证
2. 典型故障的预防性处理：针对Windows/Mac不同平台提前识别依赖冲突
3. 开发思维的体系化建立：理解NCC特有的"前后端分离但协同"的设计哲学

1. 开发环境基础准备

1.1 硬件与操作系统要求

NCC开发对硬件配置有较高要求，建议满足以下最低配置：

特别注意：Mac M1芯片需通过Rosetta 2转译运行x86架构的JDK，建议分配至少2GB的Docker内存配额

1.2 必备软件安装清单

按依赖顺序安装以下组件（所有链接均来自官方镜像源）：

# JDK安装验证（需1.8+版本） java -version # 预期输出：java version "1.8.0_301" # Maven配置检查 mvn -v # 应显示Apache Maven 3.6.3及以上版本 # Node.js版本管理（推荐使用nvm） nvm install 14.17.6 nvm use 14.17.6

关键组件版本对照表：

2. YonBuilder工具链深度配置

2.1 IDE定制化安装

YonBuilder作为NCC官方开发工具，实质是基于Eclipse的深度定制版本。推荐按此流程安装：

1. 从用友开发者中心下载YonBuilder-for-NCC-2021.11.zip完整包
2. 解压到非中文路径（如C:\dev\yonbuilder）
3. 首次启动时选择工作空间目录（建议新建空目录）
4. 在Preferences > YonBuilder中设置：
   • NCC Runtime路径指向解压后的nccloud目录
   • 勾选Enable Hot Code Replacement
   • 设置JVM参数：-Xms2048m -Xmx4096m

<!-- 示例：pom.xml必须包含的依赖 --> <dependency> <groupId>com.yonyou.nccloud</groupId> <artifactId>nccloud-sdk</artifactId> <version>2021.11.0.RELEASE</version> </dependency>

2.2 常见安装故障排除

问题现象：启动时报Failed to load the JNI shared library

• 根本原因：JDK架构与Eclipse不匹配（32位vs64位）
• 解决方案：
  1. 检查eclipse.ini中-vm指向的JDK路径
  2. 使用java -version确认架构一致性

问题现象：插件市场连接超时

• 临时解决方案：

  # 修改hosts文件追加 101.34.26.228 marketplace.yonyou.com

3. NCC核心环境搭建实战

3.1 后端服务部署

数据库初始化脚本（PostgreSQL示例）：

CREATE USER nccloud WITH PASSWORD 'nccloud@2021'; CREATE DATABASE nccloud_dev TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'zh_CN.UTF-8'; GRANT ALL PRIVILEGES ON DATABASE nccloud_dev TO nccloud;

关键目录结构说明：

ncchome ├── bin # 启动脚本 ├── conf # 配置文件 │ └── server.xml # 服务端口配置 ├── hotwebs # 前端静态资源 │ └── WEB-INF ├── modules # 后端业务模块 │ └── META-INF └── patches # 补丁目录

3.2 前端工程初始化

前端依赖安装的黄金法则：

1. 始终在项目根目录执行：

   npm config set registry https://registry.npmmirror.com npm install -g @yonyou/ncc-cli

2. 模块开发时使用：

   ncc create-module train # 创建培训模块 cd train && npm install

典型目录结构：

src ├── components # 公共组件 ├── config # 路由配置 ├── locales # 国际化资源 ├── models # 数据模型 ├── pages # 页面组件 │ └── BillForm # 单据表单 └── services # 接口服务

4. 开发调试全流程演练

4.1 后端服务调试技巧

在ICommonAction实现类中设置断点的正确姿势：

1. 在YonBuilder中打开Debug Configurations
2. 新建Remote Java Application配置
3. 设置：
   • Host: localhost
   • Port: 8000（默认调试端口）
   • Connection Type: Standard (Socket Attach)

// 标准服务调用示例 public class TrainActionImpl implements ICommonAction { @Override public Object query(Map<String, Object> params) { // 通过NCLocator获取服务 IUAPQueryBS queryService = NCLocator.getInstance() .lookup(IUAPQueryBS.class); // 使用MapProcessor处理结果 return queryService.executeQuery( "select * from train_bill", new MapListProcessor() ); } }

4.2 前端联调方法论

浏览器开发者工具关键操作：

1. 按F12打开调试工具
2. 在Sources面板定位到：

   webpack:///./src/pages/BillForm/index.js

3. 使用Ctrl+P快速跳转到Vue组件

跨域问题解决方案：

// config/proxy.config.js module.exports = { '/nccloud': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/nccloud': '' } } }

5. 生产级补丁发布流程

标准补丁制作步骤：

1. 后端补丁：

   mvn clean package -Dmaven.test.skip=true # 生成的zip在target/nccloud-module-train-patch.zip

2. 前端补丁：

   npm run build -- --mode=production # 手动复制dist内容到hotwebs对应目录

补丁版本管理规范：

在多年的NCC项目实施中，我们发现环境配置问题80%源于路径权限和版本冲突。建议开发者建立严格的环境检查清单，特别是在团队协作时，使用Docker统一开发环境能显著降低"在我机器上是好的"这类问题发生率。