Legend Studio本地开发环境搭建与联调指南

前言

在Legend Studio项目开发过程中，开发者经常需要同时开发核心功能模块和基于这些模块的外部项目。本文将详细介绍如何搭建高效的本地开发环境，实现Legend Studio与外部项目的无缝联调。

环境准备

假设你的开发机器上有如下目录结构：

项目目录
  |__ legend-studio   <-- Legend Studio核心项目
  |__ my-new-dsl      <-- 基于Legend Studio的外部DSL项目

两种联调方案对比

方案一：包链接方式（推荐）

适用场景：需要频繁修改Legend Studio代码并实时查看外部项目效果时。

优势：

• 修改实时生效，无需重复构建
• 开发效率高
• 支持热更新

操作步骤：

1. 确保已构建Legend Studio项目
2. 在Legend Studio根目录执行：

yarn dev:assemblage ../my-new-dsl

Webpack配置注意事项：

{
  "resolve": {
    "symlinks": false  // 确保正确处理依赖关系
  }
}

技术原理： 此方案利用Yarn的链接功能，将外部项目的依赖指向本地Legend Studio构建产物，实现代码变更的实时同步。

常见问题：

• 依赖解析冲突（如React被多次加载）
• 建议保持开发环境依赖版本一致

方案二：本地快照方式

适用场景：需要稳定测试环境或自动化测试时。

优势：

• 环境稳定
• 无需修改外部项目配置
• 适合CI/CD流程

操作步骤：

1. 在Legend Studio项目：

yarn publish:local-snapshot
yarn dev:assemblage ../my-new-dsl --snapshot

2. 在外部项目：

yarn cache clean
rm -rf ./node_modules
rm "yarn.lock" && touch "yarn.lock"

注意事项：

• 每次Legend Studio代码变更后需重新执行上述步骤
• 清理缓存是必要操作，避免使用旧版本

开发工作流

Legend Studio开发

yarn dev:ts  # 启动TypeScript编译监视模式

外部项目开发

yarn install  # 安装依赖
yarn setup    # 初始化项目
yarn dev      # 启动开发服务器
yarn dev:ts   # 启动TypeScript编译

最佳实践建议

1. 版本管理：保持两个项目的Node.js和Yarn版本一致
2. 依赖隔离：考虑使用Docker容器隔离开发环境
3. 调试技巧：
   • 在VSCode中配置复合启动配置
   • 合理使用断点调试
4. 性能优化：
   • 增量构建
   • 选择性监视关键目录

常见问题排查

1. 依赖解析失败：

   • 检查node_modules结构
   • 确认symlinks配置正确

2. 类型定义冲突：

   • 确保TypeScript版本一致
   • 检查类型定义文件路径

3. 构建产物不一致：

   • 清理构建缓存
   • 检查构建环境变量

通过本文介绍的方法，开发者可以高效地在Legend Studio和外部项目之间进行联调开发，大幅提升开发效率。根据实际需求选择合适的方案，并遵循最佳实践，可以避免许多常见问题。