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下复制四个关键目录platformlappreportrtuapuapbd这些资源文件要放置在新项目的src/目录下。去年我带的新人曾尝试跳过这步直接启动项目结果遇到JSON解析异常报错原因就是缺少这些平台级依赖。2.2 关键配置修改避坑指南配置miscellaneous.xml是必须的预处理操作。找到${nchome}\hotwebs\nccloud\WEB-INF\config下的这个文件将所有值改为false!-- 修改前 -- property nameenableJsonCheck valuetrue/ !-- 修改后 -- property nameenableJsonCheck valuefalse/轻应用目录结构需要遵循特定规范。建议在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_emailyonyou.com然后执行标准的初始化命令序列git init git remote add origin gitgit.yonyou.com:group/project.git git add . git commit -m feat: 项目初始化 git push -u origin master遇到大文件上传失败时可以调整postBuffer大小git config http.postBuffer 5242880003.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/xxx3.3 分支管理策略NCC项目推荐采用改良版Git Flowmaster生产环境对应分支仅允许合并发布分支release/*预发布分支feature/*功能开发分支hotfix/*紧急修复分支我们团队在实际使用中总结出一个技巧为长期存在的分支设置上游跟踪git branch --set-upstream-toorigin/master master git branch --set-upstream-toorigin/develop develop4. 后端环境专项配置4.1 Eclipse-NCC环境搭建后端开发需要专用的Eclipse-NCC版本与常规Java开发环境的主要区别在于必须配置ncchome环境变量需要额外的部署工具包deploy.battool.jarUAP中间件需要特殊启动参数关键启动参数示例-Dnc.runModedevelop -Dnc.server.location${FIELD_NC_HOME} -Duap.hotwebsnccloud,iuapmdm_fr -Xms128M -Xmx512M4.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%。