NCC项目从零到一：工程创建、环境配置与GitLab协同实战指南-编程阁

1. 从零开始：NCC项目创建规范与核心原则

第一次接触NCC项目开发时，很多新手会陷入"先写代码还是先搭环境"的困惑。根据我参与过7个大型NCC项目的经验，规范的工程创建流程能避免80%的后期协作问题。NCC项目与传统Web开发最大的区别在于其严格的单工程约束——每个项目必须确保前后端各自只有一个主工程，这是后续所有开发流程的基础。

在项目初始化阶段，开发人员需要明确区分两种场景：

首次开发：需要从零创建全新工程，此时要使用公司提供的脚手架工具生成标准项目结构。我推荐使用ncpub-multipage-demo这个官方模板，它已经预置了NCCloud项目所需的基础配置。
二次开发：当接手已有项目时，必须通过GitLab获取历史工程，绝对禁止手动创建新工程。去年我们团队就出现过因重复创建工程导致的代码合并灾难，最终花费两周才解决冲突。

项目创建后，要立即执行三个关键动作：

联系管理员在GitLab创建对应仓库
在本地工程根目录添加.gitignore文件，至少需要排除node_modules和dist目录
建立docs/CHANGELOG.md文件记录工程变更

特别提醒：NCC项目禁止使用中文路径！我在2021年处理过一例因中文路径导致的部署失败案例，最终发现是Ant构建工具对Unicode路径支持不完善。

2. 前端开发环境配置实战

2.1 脚手架获取与资源准备

前端环境搭建的第一步是获取正确的工程模板。与普通React/Vue项目不同，NCC项目需要特定的平台资源文件。执行以下命令获取官方脚手架：

git clone http://git.yonyou.com/nc-pub/ncpub-multipage-demo.git

接下来需要处理平台依赖资源，这是很多新手容易出错的地方。必须从NCCloud安装目录的${nchome}\hotwebs\nccloud\resources下复制四个关键目录：

platform
lappreportrt
uap
uapbd

这些资源文件要放置在新项目的src/目录下。去年我带的新人曾尝试跳过这步直接启动项目，结果遇到JSON解析异常报错，原因就是缺少这些平台级依赖。

2.2 关键配置修改避坑指南

配置miscellaneous.xml是必须的预处理操作。找到${nchome}\hotwebs\nccloud\WEB-INF\config下的这个文件，将所有值改为false：

<!-- 修改前 --> <property name="enableJsonCheck" value="true"/> <!-- 修改后 --> <property name="enableJsonCheck" value="false"/>

轻应用目录结构需要遵循特定规范。建议在src下创建mobile_[appName]格式的目录，例如处理结算管理的模块可以命名为mobile_settlement。对应的config.json需要同步更新：

{ "buildEntryPath": [ "./src/mobile_settlement/*/index.js" ], "proxy": "http://127.0.0.1:8080" }

2.3 开发调试全流程

依赖安装和项目启动看似简单，但有几个细节需要注意：

使用npm install时如果出现网络问题，建议切换为公司的内部镜像源
npm run dev启动后，浏览器自动打开的登录页面如果白屏，检查代理配置是否正确
开发过程中修改代码后，热更新如果失效，尝试手动刷新浏览器缓存

打包部署时有个实用技巧：在package.json中添加自定义脚本，可以自动将dist产物拷贝到测试服务器：

"scripts": { "deploy": "npm run build && xcopy .\\dist\\* \\\\test-server\\nccloud\\resources /Y /E" }

3. GitLab协同开发规范

3.1 首次代码提交标准化流程

新项目关联GitLab时，我强烈建议使用SSH协议而非HTTP。先配置全局用户信息：

git config --global user.name "your_name" git config --global user.email "company_email@yonyou.com"

然后执行标准的初始化命令序列：

git init git remote add origin git@git.yonyou.com:group/project.git git add . git commit -m "feat: 项目初始化" git push -u origin master

遇到大文件上传失败时，可以调整postBuffer大小：

git config http.postBuffer 524288000

3.2 日常协作最佳实践

团队协作时最容易出现的问题就是代码冲突。我们团队强制执行的规范包括：

每天至少推送一次代码（但不要超过5次）
每次推送必须包含有意义的commit message
推送前必须先执行git pull --rebase
功能开发必须创建特性分支

推荐使用以下命令流程：

# 早间同步 git checkout master git pull --rebase # 开发新功能 git checkout -b feature/xxx # ...开发过程... git add . git commit -m "feat: 实现xxx功能" git push origin feature/xxx

3.3 分支管理策略

NCC项目推荐采用改良版Git Flow：

master：生产环境对应分支，仅允许合并发布分支
release/*：预发布分支
feature/*：功能开发分支
hotfix/*：紧急修复分支

我们团队在实际使用中总结出一个技巧：为长期存在的分支设置上游跟踪：

git branch --set-upstream-to=origin/master master git branch --set-upstream-to=origin/develop develop

4. 后端环境专项配置

4.1 Eclipse-NCC环境搭建

后端开发需要专用的Eclipse-NCC版本，与常规Java开发环境的主要区别在于：

必须配置ncchome环境变量
需要额外的部署工具包（deploy.bat+tool.jar）
UAP中间件需要特殊启动参数

关键启动参数示例：

-Dnc.runMode=develop -Dnc.server.location=${FIELD_NC_HOME} -Duap.hotwebs=nccloud,iuapmdm_fr -Xms128M -Xmx512M

4.2 后端工程版本控制

后端项目共享到GitLab时，Eclipse的特殊操作流程需要特别注意：

右键项目 > Team > Share Project
选择Git仓库时勾选"Use or create repository in parent folder"
首次提交前需要执行Fetch操作同步远程变更

常见问题解决方案：

出现"rejected non-fast-forward"错误时，先执行rebase操作
空目录无法提交的问题，可以在目录中添加.gitkeep文件
忽略文件配置需要在.gitignore中添加bin/和build/

5. 全链路调试技巧

前后端联调时，我总结出三个关键检查点：

确保前端proxy配置的后端地址与实际服务一致
检查浏览器开发者工具中的Network请求是否携带正确的认证头
后端日志级别需要调整为DEBUG以便排查问题

一个典型的跨域问题解决方案是在后端添加过滤器：

response.setHeader("Access-Control-Allow-Origin", "*"); response.setHeader("Access-Control-Allow-Methods", "POST, GET"); response.setHeader("Access-Control-Max-Age", "3600"); response.setHeader("Access-Control-Allow-Headers", "Content-Type");

实际开发中，建议使用Postman先验证接口可用性，再对接前端代码。我们项目组现在都养成了先写API文档再开发的习惯，效率提升了至少30%。