标题: Vite SPA 插件 说明: > 用于构建Fusion框架单页应用程序的Vite插件. 自动生成 HTML 模板、 MSAL 认证拖曳, 服务发现接线、门户清单装入和认证 API通过服务员代理. 标记 :

• 聚变框架
• 维特-插件
• 语气
• 应用开发
• 门户开发
• dev 服务器
• 认证
• 服务发现
• 服务人员
• 等值
• 非生产 关键词 :
• '@equinor/suplic-framework-vite-plugin-spa' (英语)
• 聚变框架
• 维特
• 温泉
• 插件
• 发展
• 非生产
• 毫萨尔
• 服务人员
• 门户

@ equinor/ 聚变框架- vite- plugin- spa

用于构建Fusion框架单页应用程序(SPA)的Vite插件. 它生成一个 HTML 外壳, 靴子陷阱 MSAL 认证和服务发现, 通过列表加载一个传送门, 并注册一个服务员, 将 Bearer 令牌注入向外的 API 请求中.

[叹息] 此插件用于 非生产发展环境 只有这个.

[尖叫声] 此插件设计用于 @equinor/fusion-framework-cli。 CLI 脚手架自动设置所有所需的配置.

独立使用是需要深入了解融合框架内部的高级设想。 以下文件涵盖了需要者的全部配置表面.

它会做什么

[TIP] 需要渲染的门户来源于:

• A 类 本地 npm 软件包 (例如:. @equinor/fusion-framework-dev-portal, CLI 使用的默认值)
• 这个 融合门户服务 (使用门户标识符)
• 任意 自定义门户 执行 render 函数

插件是如何工作的

flowchart
  A[Vite HTML request] -->|index.html| B[Plugin serve SPA]
  B -->|bootstrap.js| C[Initialize Fusion Framework]
  C --> D[Register Service Worker]
  C -->|"/portals/{portalId}@${portalTag}"| E[Fetch Portal Manifest]
  E -->|manifest.build.config| F[Fetch Portal Configuration]
  F -->|manifest.build.entrypoint| G[Import Portal Source]
  G -->|"Fusion Instance"| H[Render Portal]

  style A fill:#F00,stroke:#333,stroke-width:1px
  style H fill:#00F,stroke:#333,stroke-width:1px

流程解释:

1. Vite HTML 请求:插件会钩入Vite dev-server并截取SPA请求.
2. 服务于SPA: 该插件通过返回 index.html 文档.
3. 初始化融合框架数字 : bootstrap.js 已装入
   • 配置框架(例如 MSAL、服务发现)
   • 初始化框架
   • 登记服务人员(与聚变框架的联系)
4. 获取端口声明:框架获取描述要加载的门户的运算表.
5. 获取端口配置: 获取门户的额外配置.
6. 装入端口源文件: 传送门的主要条目文件根据"通货单"加载.
7. 传送门户: 将"融合"框架的"传送"传送出门户.

开始

[尖叫声] 此插件主要设计为与 融合框架CLI。 CLI 脚手架所有所需的配置和接线自动.

独立使用需要您自己提供认证,服务发现,门户加载,服务人员配置. 见 配置选项 见下文.

安装

pnpm add -D @equinor/fusion-framework-vite-plugin-spa

最小维特配置

// vite.config.ts
import { defineConfig } from 'vite';
import { fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';

export default defineConfig({
  plugins: [
    fusionSpaPlugin({
      generateTemplateEnv: () => ({
        title: 'My App',
        portal: { id: 'my-portal' },
        serviceDiscovery: {
          url: 'https://my-server.com/service-discovery',
          scopes: ['api://my-app/scope'],
        },
        msal: {
          tenantId: 'my-tenant-id',
          clientId: 'my-client-id',
          redirectUri: 'http://localhost:3000/auth-callback',
          requiresAuth: 'true',
        },
      }),
    }),
  ],
});

配置选项

这个 fusionSpaPlugin (也导出为 plugin) 接受一个 PluginOptions 具有下列属性的对象:

模板环境( E)generateTemplateEnv(中文(简体) )

这个 generateTemplateEnv 回调返回形状匹配的对象 FusionTemplateEnv所有属性被平整为 FUSION_SPA_* 构建时的环境变量.

以下是一个全面的例子:

fusionSpaPlugin({
  generateTemplateEnv: () => ({
    // HTML page title
    title: 'My App',

    // Portal configuration: specify which portal to load
    portal: {
      id: 'my-portal', // Portal ID to load and render
      // Can be:
      //   1. A package name (e.g. '@equinor/fusion-framework-dev-portal', default for CLI)
      //   2. An ID from the Fusion Portal Service
      //   3. Any other configured portal ID
      tag: 'latest', // (Optional) Version tag (defaults to 'latest')
      proxy: false, // (Optional) Whether to proxy portal requests through /portal-proxy (defaults to false)
    },

    // Service Discovery configuration
    serviceDiscovery: {
      url: 'https://my-server.com/service-discovery',
      scopes: ['api://my-app/scope'],
    },

    // MSAL (Microsoft Authentication Library) configuration
    msal: {
      tenantId: 'my-tenant-id',
      clientId: 'my-client-id',
      redirectUri: 'https://my-app.com/auth-callback',
      requiresAuth: 'true',
      mock: 'true', // (Optional) Use mock authentication for CI/Playwright
    },

    // Service Worker configuration for API proxying and authentication
    serviceWorker: {
      resources: [
        {
          url: '/app-proxy',
          rewrite: '/@fusion-api/app',
          scopes: ['xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default'],
        },
      ],
    },
  })
});

门户代理

门户代理功能允许您通过一个 /portal-proxy 路径前缀。 启用时, 插件将尝试从 URL 前缀装入门户代码 /portal-proxy/,这在与需要截取和路由门户请求的代理服务器或开发环境合作时可能有用.

行为:

• proxy: true • 门户负荷 /portal-proxy/{assetPath}/{templateEntry} (允许代理拦截)
• proxy: false • 门户负荷 {assetPath}/{templateEntry} (直接装入)

配置选项 :

• proxy: 当设定为 true,门户入口点将使用 /portal-proxy

何时使用门户代理 :

• 需要通过代理服务门户资产的开发环境
• 需要通过特定路径传送门户的部署设想
• 使用 API 服务插件进行高级门户加载时

示例

portal: {
  id: 'my-portal',
  tag: 'latest',
  proxy: true, // Portal will be loaded from /portal-proxy/{assetPath}/{templateEntry}
}

见 @equinor/ inform-framework-vite-plugin-api-service (英语) 用于高级 API 代理.

服务发现

配置Fusion框架用于在运行时发现后端服务URL的端点.

• url ——服务发现配置的端点 URL
• scopes ——认证请求到服务发现端点所需的OAuth范围

MSAL 认证

通过微软认证库(MSAL)配置 Azure AD认证.

• tenantId - Azure AD租户身份识别符
• clientId - 在Azure AD注册的申请(客户)ID
• redirectUri —— 认证后重定向到 URL
• requiresAuth (可选,字符串) 何时 'true',自动提示登录第一个负载
• mock (可选,字符串) 何时 'true',使用模拟认证而不是 Entra ID

服务工作者

服务员截取输出的取取请求, 与配置匹配 ResourceConfiguration 模式,可选地重写 URL,并附加一个 Bearer 符号.

如何运作

sequenceDiagram
  participant App as Application
  participant SW as Service Worker
  participant Main as Fusion Framework
  participant API as API Server

  App->>SW: fetch('/app-proxy/assets/some-app/resource.json')
  alt Route matches a registered resource
    SW->>Main: Request auth tokens for scopes
    Main-->>SW: Return tokens
    SW->>SW: Rewrite URL to /@fusion-api/app/assets/some-app/resource.json
    SW->>API: fetch with auth headers
    API-->>SW: Response
    SW-->>App: Return response
  else Route does not match any resource
    SW-->>App: Let request pass through (no interception)
  end

服务员拦截网络请求,可以:

1. 附加 OAuth 守护符以匹配请求
2. 重写代理请求的 URL
3. 通过未修改的请求传递未匹配的请求

资源配置

表格中的每个条目 resources 数组为 a ResourceConfiguration 对象 :

完整示例

以下是服务工作者在行动中的详细例子:

// Service Worker configuration example
const serviceWorker = {
  resources: [
    {
      url: '/app-proxy',
      rewrite: '/@fusion-api/app',
      scopes: [
        '2bed749c-843b-413d-8b17-e7841869730f/.default',
        '8c24cf81-de7a-435b-ab74-e90b1a7bda0a/.default',
      ],
    },
  ],
};

// Example: Making a request in your application code
fetch('/app-proxy/assets/some-app/resource-path/resource.json');

请求处理流程

当上面 fetch 提出以下要求:

1. 服务员截取符合 /app-proxy 模式
2. 它向主线程发送一个消息, 请求为指定的范围提供认证符
3. 主线程生成必要的认证符
4. 服务工作者重写 URL 从 /app-proxy/assets/some-app/resource-path/resource.json 改为 /@fusion-api/app/assets/some-app/resource-path/resource.json
5. 它在请求中添加认证头并针对重写的 URL 执行
6. 回复返回到应用程序中, 如原 URL 被调用

[TIP] 这个 url 路径不需要对应一个实际终点——它只是一个用于匹配请求的图案. 这使得您可以在生产环境中模拟代理服务而无需更改您的应用程序代码.

[TIP] 为增强发展能力,考虑使用 @equinor/fusion-framework-vite-plugin-api-service 插件 。 此插件创建了动态代理服务, 可以处理请求到 /@fusion-api/app 通过在dev-server中截取它们并基于服务发现配置进行路由.

遥测

插件通过配置控制台遥测 @equinor/fusion-framework-module-telemetry。相位图到整数:

控制控制台输出

设定 FUSION_SPA_TELEMETRY_CONSOLE_LEVEL 到显示的最小关卡。 默认是 1 (资料).

FUSION_SPA_TELEMETRY_CONSOLE_LEVEL=2  # Warning and above

对于高级遥测(如应用透视),提供a 自定义拖曳文件。 。 。 .

使用时 @equinor/fusion-framework-dev-server,默认的靴子陷阱也支持 OTLP通过遥测模块的公用日志 OtlpAdapter外加标准的 OpenTelection 浏览器请求跟踪和W3C传播. 设定 FUSION_DEV_SERVER_OTLP_ENDPOINT 在应用程序的 dev-server 进程中;不需要更改应用程序代码. Dev服务器拥有环境桥和同源的收集路径. 鞋带 只检查端点是否配置; 仅服务 dev- server 桥接控制 启动 明确配置的应用程序适配器和现有的全球跟踪器供应商 优先级。 见 dev-server 遥测配置。 。 。 .

通过配置 .env 文件

插件读取环境变量 .env 文件( 通过 Vite ) loadEnv和 将它们合并到 来自 generateTemplateEnv。这使得您可以将机密和每个环境的值从源代码中保留出来.

命名公约

1. 前缀所有变量 FUSION_SPA_ (或您的习惯) templateEnvPrefix) (中文(简体) ).
2. 将嵌入对象路径转换为 UPPER_SNAKE_CASE (例如:. serviceDiscovery.url → FUSION_SPA_SERVICE_DISCOVERY_URL) (中文(简体) ).
3. 将数组和对象序列化为JSON字符串.

映射示例

// JavaScript configuration
{
  serviceWorker: {
    resources: [...],
  },
}

// Becomes this environment variable
FUSION_SPA_SERVICE_WORKER_RESOURCES=[...]

// And can be accessed in your code as
import.meta.env.FUSION_SPA_SERVICE_WORKER_RESOURCES

完成 .env 示例

# Page title
FUSION_SPA_TITLE=My App

# Portal manifest
FUSION_SPA_PORTAL_ID=my-portal
FUSION_SPA_PORTAL_TAG=latest
FUSION_SPA_PORTAL_PROXY=false

# Service Discovery
FUSION_SPA_SERVICE_DISCOVERY_URL=https://my-server.com/service-discovery
FUSION_SPA_SERVICE_DISCOVERY_SCOPES=[api://my-app/scope]

# MSAL
FUSION_SPA_MSAL_TENANT_ID=my-tenant-id
FUSION_SPA_MSAL_CLIENT_ID=my-client-id
FUSION_SPA_MSAL_REDIRECT_URI=https://my-app.com/auth-callback
FUSION_SPA_MSAL_REQUIRES_AUTH=true
# Set to skip Entra ID and sign in a mock user instead — use together with a mock server (see below)
FUSION_SPA_MSAL_MOCK=true
# Optional: standalone mock-server origin used for session-scoped token acquisition
FUSION_SPA_MSAL_MOCK_SERVER_URL=http://localhost:4010

# Telemetry
FUSION_SPA_TELEMETRY_CONSOLE_LEVEL=2

# Service Worker (JSON string)
FUSION_SPA_SERVICE_WORKER_RESOURCES=[{"url":"/app-proxy","rewrite":"/@fusion-api/app","scopes":["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default"]}]

[TIP] 使用 generateTemplateEnv 在开发类型安全和更容易调试的过程中。 使用 .env 用于 CI/CD 和部署的文档.

[大 这个 .env 文件必须是在工程根中(或由 Vite 指定的目录) envDir) (中文(简体) ). 值来自 .env 文件覆盖匹配值从 generateTemplateEnv。 。 。 .

运行针对 Mock 客户端( CI / Playwright)

运行 CI 和 Playwright 套房对接独立模拟服务器,所以认证和 服务发现留在本地 :

ffc mock-server ./mocks --port 4010
ffc app dev --mock http://localhost:4010

设置 FUSION_SPA_MSAL_MOCK=true 将真实的 MSAL 客户端交换为 @equinor/fusion-framework-module-msal/mock,在默认的模拟用户中标出 Entra ID重定向或弹出. 混音符号没有签名,所以真正的"融合"服务拒绝了它们. ffc app dev 财务报告和审定财务报表 ffc app serve 因此,还将服务发现发送给模拟服务器 每当嘲笑的真主来临的时候 FUSION_SPA_MSAL_MOCK_SERVER_URL,或 http://localhost:4010 何时 仅限 FUSION_SPA_MSAL_MOCK 已经设定.

FUSION_SPA_MSAL_MOCK=true

[大 一个直接的 Vite 设置必须指向 FUSION_SPA_SERVICE_DISCOVERY_URL (或dev服务器的) 服务发现 URL)在模拟服务器上也. 否则,每个页面加载都会发出一个模拟符号 到真正的服务发现并失败 401。 。 。 .

默认为通用的模拟符号 Test User。要在运行时选择和切换用户,启动 带有浏览器来源的独立的模拟服务器明确允许,然后将应用程序指向它:

ffc mock-server ./mocks --port 4010 --allow-origin http://localhost:3000
ffc app dev --mock http://localhost:4010

这个 --mock 选项允许模拟认证,并向SPA提供模拟服务器 URL。 A 类 直接 Vite 设置可以通过 FUSION_SPA_MSAL_MOCK=true 财务报告和审定财务报表 FUSION_SPA_MSAL_MOCK_SERVER_URL=http://localhost:4010。 。 。 .

Playwright 和其他 cookie-aware HTTP 客户端可以通过 createMockAuth 从 @equinor/fusion-openapi-mock-server。独立模拟服务器存储用户/浏览器 为Fusion SAML要求的每套范围,上下文和发出一个未签名的OBO式符号。 这个 支持不重新启动应用程序或dev服务器而切换和平行人物;见 剧作家指南。 。 。 .

模拟认证并不嘲弄API的其余表面——服务发现和 任何后端的呼号,门户网站仍然会点击真实的URL,除非您也覆盖它们. 使用 dev 服务器的 api.routes编号 :api.processServices 选项(参见 @equinor/fusion-framework-dev-server 要截取的文件 这些请求有固定的答复.

高级自定义

提供自定义模板

通过通过一个 template 字符串到插件中。 占位符使用 %VAR% 语法来源 Vite 的 HTML 常数替换。 。 。 .

[尖叫声] 自定义模板绕过默认结构. 您负责加载脚本, 并确保正确的文档结构 .

示例自定义模板

// Define your custom HTML template
const template = `
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>%MY_CUSTOM_TITLE%</title>
    <script type="module" src="./src/my-custom-bootloader"></script>
  </head>
  <body>
    <h1>%MY_CUSTOM_PROPERTY%</h1>
    <div id="app"></div>
  </body>
</html>
`;

// Configure Vite with your custom template
import { defineConfig } from 'vite';
import { createViteSPAPlugin } from '@equinor/fusion-framework-vite-plugin-spa';

// Custom prefix for environment variables
const templateEnvPrefix = 'MY_CUSTOM_';

export default defineConfig({
  // Define environment variables to inject into the template
  define: {
    [`import.meta.env.${templateEnvPrefix}PROPERTY`]: '"my-custom-value"',
    [`import.meta.env.${templateEnvPrefix}TITLE`]: '"My Application"',
  },
  // Use the custom template with the plugin
  plugins: [createViteSPAPlugin({ template, templateEnvPrefix })],
});

[TIP] 关于HTML模板变量替换如何在Vite工作的更详细信息,请参见: 虚拟文档。 。 。 .

提供自定义靴子

对于更多的控制,您可以指定一个处理应用程序初始化的自定义的靴子陷阱文件:

fusionSpaPlugin({
  generateTemplateEnv: () => {
    return {
      // Points to your custom bootstrap file
      bootstrap: 'src/my-custom-bootloader.ts',
    }
  }
});

执行您的自定义启动程序

使用自定义的启动器时,您需要处理通常由默认启动器管理的所有初始化逻辑,包括服务人员注册:

// custom-bootloader.ts
import { registerServiceWorker } from '@equinor/fusion-framework-vite-plugin-spa/html';
import initializeFramework from './my-custom-framework.js';

// Initialize your framework and register the service worker
const app = await initializeFramework();
registerServiceWorker(app);

// Additional custom initialization code
document.addEventListener('DOMContentLoaded', () => {
  console.log('Application fully loaded');
});

[尖叫声] 在使用自定义的启动器时,默认的服务工人注册会被绕过. 您必须明确打电话 registerServiceWorker() 如上例所示,您可以在自定义的启动器中维护此功能.

实例

基本 SPA 有反应

// vite.config.ts
import { defineConfig } from 'vite';
import { plugin as fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    fusionSpaPlugin({
      generateTemplateEnv: () => ({
        title: 'My React App',
        portal: { id: 'my-portal' },
        serviceDiscovery: {
          url: 'https://dev-server.com/service-discovery',
          scopes: ['api://my-app/user.read'],
        },
        msal: {
          tenantId: process.env.TENANT_ID,
          clientId: process.env.CLIENT_ID,
          redirectUri: 'http://localhost:3000/auth-callback',
          requiresAuth: 'true',
        },
        telemetry: {
          consoleLevel: 2, // Show Warning, Error, and Critical events
        },
      }),
    }),
  ],
});

使用 API 服务插件

// vite.config.ts
import { defineConfig } from 'vite';
import { plugin as fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
import { plugin as apiServicePlugin } from '@equinor/fusion-framework-vite-plugin-api-service';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    fusionSpaPlugin({
      generateTemplateEnv: () => ({
        title: 'API Service Example',
        // Portal to load
        portal: {
          id: 'my-portal',
          tag: 'latest',
        },
        serviceDiscovery: {
          url: 'https://dev-server.com/service-discovery',
          scopes: ['api://my-app/user.read'],
        },
        serviceWorker: {
          resources: [
            {
              url: '/api-proxy',
              rewrite: '/@fusion-api/service',
              scopes: ['api://backend-service/.default'],
            },
          ],
        },
      }),
    }),
    // API Service plugin enables portal loading from service discovery
    apiServicePlugin(),
  ],
});

见 API 服务插件文件 更多细节.

解决问题

共同问题

已知问题

最佳做法

• 将秘密排除在源代码之外——使用 .env 文件或 CI/CD 变量.
• 使用 API 服务插件 用于开发期间的高级代理路由.
• 在使用自定义模板或靴子拖放文件时,总是核查服务人员注册和认证流程.

捐款

欢迎投稿、错误报告和特性请求! 见 捐款额 准则.