指南
API
博客
指南
API
博客
简体中文

模块链接

Esmx 框架提供了一套完整的模块链接机制，用于管理服务间的代码共享和依赖关系。该机制基于 ESM（ECMAScript Module）规范实现，支持源码级别的模块导出和导入，以及完整的依赖管理功能。

核心概念

模块导出

模块导出是将服务中的特定代码单元（如组件、工具函数等）以 ESM 格式对外暴露的过程。支持两种导出类型：

  • 源码导出：直接导出项目中的源代码文件
  • 依赖导出：导出项目使用的第三方依赖包

模块链接

模块导入是在服务中引用其他服务导出的代码单元的过程。支持多种安装方式：

  • 源码安装：适用于开发环境，支持实时修改和热更新
  • 软件包安装：适用于生产环境，直接使用构建产物

模块导出

配置说明

在 entry.node.ts 中配置需要导出的模块：

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    modules: {
5        exports: [
6            // 导出源码文件
7            'root:src/components/button.vue',  // Vue 组件
8            'root:src/utils/format.ts',        // 工具函数
9            // 导出第三方依赖
10            'npm:vue',                         // Vue 框架
11            'npm:vue-router'                   // Vue Router
12        ]
13    }
14} satisfies EsmxOptions;

导出配置支持两种类型：

  • root:*：导出源码文件，路径相对于项目根目录
  • npm:*：导出第三方依赖，直接指定包名

模块导入

配置说明

在 entry.node.ts 中配置需要导入的模块：

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    modules: {
5        // 链接配置
6        links: {
7            // 源码安装：指向构建产物目录
8            'ssr-remote': './node_modules/ssr-remote/dist',
9            // 软件包安装：指向包目录
10            'other-remote': './node_modules/other-remote'
11        },
12        // 导入映射设置
13        imports: {
14            // 使用远程模块中的依赖
15            'vue': 'ssr-remote/npm/vue',
16            'vue-router': 'ssr-remote/npm/vue-router'
17        }
18    }
19} satisfies EsmxOptions;

配置项说明：

  1. imports：配置远程模块的本地路径

    • 源码安装：指向构建产物目录（dist）
    • 软件包安装：直接指向包目录

  2. externals：配置外部依赖

    • 用于共享远程模块中的依赖
    • 避免重复打包相同依赖
    • 支持多个模块共享依赖

安装方式

源码安装

适用于开发环境，支持实时修改和热更新。

  1. Workspace 方式 推荐在 Monorepo 项目中使用：
package.json
1{
2    "devDependencies": {
3        "ssr-remote": "workspace:*"
4    }
5}
  1. Link 方式 用于本地开发调试：
package.json
1{
2    "devDependencies": {
3        "ssr-remote": "link:../ssr-remote"
4    }
5}

软件包安装

适用于生产环境，直接使用构建产物。

  1. NPM Registry 通过 npm registry 安装：
package.json
1{
2    "dependencies": {
3        "ssr-remote": "^1.0.0"
4    }
5}
  1. 静态服务器 通过 HTTP/HTTPS 协议安装：
package.json
1{
2    "dependencies": {
3        "ssr-remote": "https://cdn.example.com/ssr-remote/1.0.0.tgz"
4    }
5}

软件包构建

配置说明

在 entry.node.ts 中配置构建选项：

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    // 模块导出配置
5    modules: {
6        exports: [
7            'root:src/components/button.vue',
8            'root:src/utils/format.ts',
9            'npm:vue'
10        ]
11    },
12    // 构建配置
13    pack: {
14        // 启用构建
15        enable: true,
16
17        // 输出配置
18        outputs: [
19            'dist/client/versions/latest.tgz',
20            'dist/client/versions/1.0.0.tgz'
21        ],
22
23        // 自定义 package.json
24        packageJson: async (esmx, pkg) => {
25            pkg.version = '1.0.0';
26            return pkg;
27        },
28
29        // 构建前处理
30        onBefore: async (esmx, pkg) => {
31            // 生成类型声明
32            // 执行测试用例
33            // 更新文档等
34        },
35
36        // 构建后处理
37        onAfter: async (esmx, pkg, file) => {
38            // 上传到 CDN
39            // 发布到 npm 仓库
40            // 部署到测试环境等
41        }
42    }
43} satisfies EsmxOptions;

构建产物

your-app-name.tgz ├── package.json # 包信息 ├── index.js # 生产环境入口 ├── server/ # 服务端资源 │ └── manifest.json # 服务端资源映射 ├── node/ # Node.js 运行时 └── client/ # 客户端资源 └── manifest.json # 客户端资源映射

发布流程

1# 1. 构建生产版本
2esmx build
3
4# 2. 发布到 npm
5npm publish dist/versions/your-app-name.tgz
ON THIS PAGE