PagePlug项目内网部署前端启动问题解决方案

问题背景

在企业内网环境下部署PagePlug项目时，开发人员可能会遇到前端启动失败的问题。具体表现为系统提示无法解析@shared/dsl模块，即使node_modules目录中已经包含了该依赖项。

问题现象

当在内网Linux机器上尝试启动PagePlug前端时，控制台会显示模块解析错误：

Module not found: Error: Can't resolve '@shared/dsl'

根本原因分析

经过深入排查，发现该问题主要由以下因素导致：

1. 内网环境限制：由于部署环境处于内网，无法直接通过yarn install安装依赖，需要预先在外网下载好node_modules后传入内网。

2. 项目结构特殊性：PagePlug采用了monorepo架构，共享代码通过@shared命名空间引用，这些共享模块位于packages目录下，而非传统的node_modules中。

3. 软链接失效：在内网环境下，原先在外网建立的node_modules与packages之间的软链接关系无法正常迁移。

解决方案

要彻底解决此问题，需要执行以下步骤：

1. 完整迁移项目结构：

   • 不仅需要迁移client/node_modules目录
   • 还必须同时迁移项目根目录下的packages文件夹
   • 确保packages目录结构与外网开发环境完全一致

2. 重建项目依赖关系：

   • 在迁移完成后，建议在内网环境中执行yarn install --check-files命令
   • 此命令会验证并修复可能存在的依赖关系问题

3. 环境变量配置：

   • 检查.yarnrc.yml配置文件
   • 确保nodeLinker设置正确（通常应为node-modules）

最佳实践建议

对于类似PagePlug这样的monorepo项目，在内网环境部署时建议：

1. 完整项目备份：将整个项目目录（包括node_modules和packages）一起打包迁移，而非单独迁移部分目录。

2. 版本一致性检查：确保内网环境的Node.js和Yarn版本与外网开发环境完全一致。

3. 部署前验证：在外网环境先进行完整构建测试，确认无问题后再迁移到内网。

技术原理

理解这一问题的关键在于monorepo项目的特殊结构：

• @shared/dsl这类模块实际上是项目内部的workspace依赖
• Yarn会通过特殊的链接机制将这些本地包"安装"到node_modules中
• 当仅迁移node_modules而缺少packages源码时，这些链接就会失效

通过完整迁移项目结构，可以确保所有workspace依赖关系得到保持，从而解决模块解析失败的问题。