ikaros-web 使用文档

target

编译的平台，该值影响底层优化逻辑。

• 类型: 'pc' | 'mobile'
• 默认值: 'pc'
• 未来支持: 该功能受限，目前仅支持 'pc'

pages

页面配置。

• 类型: Pages

• 默认值:

  {
    "index": {
      "html": "path.join(context, 'index.html')",
      "entry": "path.join(context, 'src/index')"
    }
  }

moduleFederation

模块联邦。

• 类型: ModuleFederationOptions | ModuleFederationOptions[]
• 默认值: undefined
• 参考: Module Federation

plugins

插件。

• 类型: Plugin | Plugin[]
• 参考: Rspack Plugins

loaders

loader。

• 类型: Loader[]
• 参考: Rspack Loaders

experiments

RspackExperiments。

• 类型: RspackExperiments
• 默认值: undefined
• 参考: Rspack Experiments
• 参考: Babel Plugin Import

cdnOptions

• 类型：CdnPluginOptions
• 默认值：undefined
• 说明：用于在构建过程中将外部依赖注入到 HTML 中，支持开发和生产环境使用不同的 CDN 源。
• 参考：
  • 基础配置:

// filepath: ikaros.config.ts
import { defineConfig } from '@ikaros-cli/ikaros'

export default defineConfig({
  cdnOptions: {
    modules: [
      {
        name: 'vue', // 模块名称
        var: 'Vue', // 全局变量名
        path: 'dist/vue.runtime.min.js', // JS 文件路径
      },
      {
        name: 'element-plus',
        var: 'ElementPlus',
        path: 'dist/index.full.min.js',
        style: 'dist/index.css', // CSS 文件路径
      },
    ],
    // 可选：自定义 CDN URL 模板
    prodUrl: 'https://unpkg.com/:name@:version/:path',
    devUrl: ':name/:path',
    // 可选：启用跨域配置
    crossOrigin: 'anonymous',
  },
})

CDN 配置项说明

CdnModule 配置

| 参数 | 类型 | 必填 | 说明 | | ------- | -------- | ---- | -------------------------------------------- | | name | string | 是 | 模块名称，需与 package.json 中的名称一致 | | var | string | 否 | 模块导出的全局变量名 | | version | string | 否 | 指定版本号，未指定时自动从 node_modules 获取 | | path | string | 否 | 主 JS 文件路径 | | paths | string[] | 否 | 额外的 JS 文件路径列表 | | style | string | 否 | 主 CSS 文件路径 | | styles | string[] | 否 | 额外的 CSS 文件路径列表 | | cssOnly | boolean | 否 | 是否仅加载 CSS 文件 | | prodUrl | string | 否 | 指定该模块的生产环境 CDN URL 模板 | | devUrl | string | 否 | 指定该模块的开发环境 CDN URL 模板 |

插件选项

| 参数 | 类型 | 默认值 | 说明 | | ----------- | ----------------- | ---------------------------------------- | --------------------- | | modules | CdnModule[] | - | CDN 模块配置列表 | | prodUrl | string | https://unpkg.com/:name@:version/:path | 生产环境 CDN URL 模板 | | devUrl | string | :name/:path | 开发环境 CDN URL 模板 | | crossOrigin | boolean | string | false | 跨域资源配置 |

URL 模板

支持以下占位符：

• :name - 模块名称
• :version - 模块版本号
• :path - 资源路径

使用示例

基础用法

cdnOptions: {
  modules: [
    {
      name: 'vue',
      var: 'Vue',
      path: 'dist/vue.runtime.min.js',
    },
  ]
}

使用自定义 CDN

cdnOptions: {
  modules: [
    {
      name: "vue",
      var: "Vue",
      path: "dist/vue.runtime.min.js",
    },
  ];
  // 仅在生产环境时生效
  prodUrl: "https://cdn.jsdelivr.net/npm/:name@:version/:path",
}

加载多个资源

cdnOptions: {
  modules: [
    {
      name: 'element-plus',
      var: 'ElementPlus',
      path: 'dist/index.full.min.js',
      paths: ['dist/locale/zh-cn.min.js'],
      style: 'dist/index.css',
      styles: ['dist/theme-chalk/dark.css'],
    },
  ]
}

仅加载样式

cdnOptions: {
  modules: [
    {
      name: 'normalize.css',
      style: 'normalize.css',
      cssOnly: true,
    },
  ]
}

注意事项

1. 确保模块名称与 package.json 中的名称一致
2. 建议在生产环境中明确指定版本号
3. 使用自定义 CDN 时注意资源路径的正确性
4. 开发环境默认使用本地 node_modules 中的文件

server

dev 服务相关，该对象下的值不影响生产环境。

• 类型: object
  • port: 服务器端口号，空则自动获取。
    • 类型: number
    • 默认值: undefined
  • proxy: webpack-server 服务器代理。
    • 类型: import('@rspack/dev-server').Configuration['proxy']
    • 默认值: undefined
    • 参考: DevServer Proxy
  • https: https 配置。
    • 类型: boolean | import('https').ServerOptions
    • 默认值: false
    • 参考: DevServer HTTPS

css

css loader 配置。

• 类型: CssLoaderOptions
• 参考: LightningCSS Options
• 参考: Stylus Options
• 参考: Less Options
• 参考: Sass Options

build

构建配置。

• 类型: object
  • base: 资源前缀，值得注意的是 './' 只会被原封不动的作为所有资源的前缀，如果你想根据 html 定位应该填 'auto'。
    • 类型: string
    • 默认值: '/'
  • assetsDir: 资产包裹目录，只在生产环境下生效。
    • 类型: string
    • 默认值: undefined
  • gzip: 是否输出 Gzip 版，只在生产环境下生效。
    • 类型: boolean
    • 默认值: false
  • sourceMap: 生成映射源代码文件，只在生产环境下生效。
    • 类型: boolean
    • 默认值: false
  • outDirName: 输出的目录名称，只在生产环境下生效。
    • 类型: string
    • 默认值: "dist"
  • outReport: 是否输出打包分析报告，只在生产环境下生效。
    • 类型: boolean
    • 默认值: false
  • cache: 是否缓存编译结果。
    • 类型: boolean
    • 默认值: false

resolve

resolve 配置。

• 类型: object
  • alias: 路径别名。
    • 类型: Record<string, string>
    • 默认值: {'@': path.join(context,'src')}
    • 参考: Resolve Alias
  • extensions: 默认后缀。
    • 类型: string[]
    • 默认值: [".js", ".json", ".wasm",'.mjs', '.jsx', '.ts', '.tsx']
    • 参考: Resolve Extensions

辅助工具函数

defineConfig

定义配置的辅助工具函数。

• 类型: (config: UserConfigWebExport) => UserConfigWebExport