fix: making some variables more semantic.

Author: chilingling

designer-demo/tests/localCdnCustomConfig.test.js

@@ -72,7 +72,7 @@ describe('localCDN 自定义配置测试', () => {
     const updatedViteConfig = originalViteConfig.replace(
       'const baseConfig = useTinyEngineBaseConfig({',
       `const baseConfig = useTinyEngineBaseConfig({
-    localCdnConfig: {
+    importMapLocalConfig: {
       importMap: { 
         imports: {
           'vue': "\${VITE_CDN_DOMAIN}/vue\${versionDelimiter}3.4.21\${fileDelimiter}/dist/vue.runtime.esm-browser.prod.js"

docs/README.md

@@ -46,7 +46,7 @@
   - [区块局域网发布方案(Node.js服务端)](./solutions/block-lan-release-solution.md)
   - [设计器中引入第三方组件库](./solutions/third-party-library-in-designer.md)
   - [物料同步方案](./solutions/material-sync-solution.md)
-  - [本地化CDN方案](./solutions/local-cdn.md)
+  - [本地化CDN方案](./solutions/import-map-local.md)
 - 扩展能力介绍
   - [新架构介绍](./extension-capabilities-overview/new-architecture.md)
   - [注册表](./extension-capabilities-overview/registry.md)

docs/solutions/local-cdn.md docs/solutions/import-map-local.mddocs/solutions/local-cdn.md renamed to docs/solutions/import-map-local.md

@@ -1,18 +1,25 @@
-# 本地化CDN方案
+# 本地化 import-map CDN方案
 
 ## 概述
 
-本地化CDN是一种在生产环境中将远程CDN资源替换为本地文件的解决方案。它具有以下优势：
+TinyEngine 在画布和预览都使用了 import-map 的方案来依赖 vue、vue-i18n 以及物料等依赖，这些 import-map 默认会使用 npmmirror 的 CDN。
+但是，在一些企业化的场景中，我们无法依赖这种外部的 CDN。（可用性和稳定性要求。）
+
+当前可以采取的方案有：
+- 搭建私网的 unpkg
+- 使用本文档介绍的 import-map CDN 本地化方案
+
+本地化 import-map CDN是一种在构建时，将 import-map 所需的远程CDN资源替换为构建产物中的文件的解决方案。它具有以下优势：
 
 1. 减少对外部CDN的依赖，提高应用的可靠性
-2. 在离线环境或内网环境中使用CDN资源
-3. 加快资源加载速度，提升应用性能
+2. 在离线环境或内网环境中访问 import-map 所需的 CDN 资源。
+3. 加快资源加载速度，提升应用性能。
 
 ## 使用方法
 
-### 修改环境变量使用本地化CDN
+### 修改环境变量使用 import-map CDN 本地化方案
 
-要启用本地化CDN功能，请按照以下步骤操作：
+要启用 import-map CDN 本地化功能，请按照以下步骤操作：
 
 1. 修改环境变量
 
@@ -39,7 +46,7 @@ VITE_LOCAL_CDN_PATH=./local-cdn-static
 
 ```javascript
 const baseConfig = useTinyEngineBaseConfig({
-  localCdnConfig: {
+  importMapLocalConfig: {
     importMap: { imports: { ... } },
     copy: { ... }
   }
@@ -53,13 +60,13 @@ CDN 本地化接受以下配置选项：
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| localCdnConfig | Object | `{ importMap: { imports: {} }, copy: {} }` | 本地CDN配置对象 |
-| localCdnConfig.importMap | Object | `{ imports: {} }` | 导入映射配置，定义需要本地化的CDN依赖 |
-| localCdnConfig.copy | Object | `{}` | 自定义复制配置，可以覆盖特定包的默认配置 |
+| importMapLocalConfig | Object | `{ importMap: { imports: {} }, copy: {} }` | 本地CDN配置对象 |
+| importMapLocalConfig.importMap | Object | `{ imports: {} }` | 导入映射配置，定义需要本地化的CDN依赖 |
+| importMapLocalConfig.copy | Object | `{}` | 自定义复制配置，可以覆盖特定包的默认配置 |
 
 #### importMap 详细说明
 
-`localCdnConfig.importMap` 是一个包含 `imports` 属性的对象，它定义了需要本地化的CDN依赖。在插件内部，它会与默认的导入映射配置合并。
+`importMapLocalConfig.importMap` 是一个包含 `imports` 属性的对象，它定义了需要本地化的CDN依赖。在插件内部，它会与默认的导入映射配置合并。
 
 import-map.json 的格式示例：
 ```json
@@ -79,14 +86,14 @@ URL格式说明：
 
 插件将解析这些URL，提取包名、版本和文件路径，然后在构建时将它们替换为本地路径。
 
-**重要说明**：如果您在 Vite 配置中传递了 `localCdnConfig.importMap`，还需要在 registry 注册表的 config 中传入同样的配置，以确保应用在运行时能正确读取自定义的 importMap 配置。例如：
+**重要说明**：如果您在 Vite 配置中传递了 `importMapLocalConfig.importMap`，还需要在 registry 注册表的 config 中传入同样的配置，以确保应用在运行时能正确读取自定义的 importMap 配置。例如：
 
 ```javascript
 // 在注册表配置中
 {
   config: {
     id: 'engine.config',
-    importMap: localCdnConfig.importMap,
+    importMap: importMapLocalConfig.importMap,
     // ... 其他配置
   }
 }
@@ -96,7 +103,7 @@ URL格式说明：
 
 #### copy 详细说明
 
-`localCdnConfig.copy` 是一个可选的配置对象，用于覆盖特定包的默认复制配置。它的结构是一个对象，键是包名，值是该包的复制配置。
+`importMapLocalConfig.copy` 是一个可选的配置对象，用于覆盖特定包的默认复制配置。它的结构是一个对象，键是包名，值是该包的复制配置。
 
 默认配置如下：
 ```javascript
@@ -179,7 +186,7 @@ VITE_CDN_DOMAIN=https://unpkg.com
 
 ### 1. 分析导入映射并收集依赖
 
-`localCdnPlugin`会分析提供的`localCdnConfig`和默认的导入映射，识别所有需要本地化的CDN依赖。这个过程包括：
+`importMapLocalPlugin`会分析提供的`importMapLocalConfig`和默认的导入映射，识别所有需要本地化的CDN依赖。这个过程包括：
 
 - 解析CDN URL获取包名、版本和文件路径
 - 合并用户配置和默认配置

packages/build/vite-config/src/default-config.js

@@ -10,7 +10,7 @@ import esbuildCopy from 'esbuild-plugin-copy'
 import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
 import visualizerCjs from 'rollup-plugin-visualizer'
 import generateComment from '@opentiny/tiny-engine-vite-plugin-meta-comments'
-import { getBaseUrlFromCli, copyBundleDeps, localCdnPlugin } from './localCdnFile/index.js'
+import { getBaseUrlFromCli, copyBundleDeps, importMapLocalPlugin } from './localCdnFile/index.js'
 import { devAliasPlugin } from './vite-plugins/devAliasPlugin.js'
 import { htmlUpgradeHttpsPlugin } from './vite-plugins/upgradeHttpsPlugin.js'
 import { canvasDevExternal } from './canvas-dev-external.js'
@@ -173,14 +173,14 @@ export function useTinyEngineBaseConfig(engineConfig) {
     const logger = console
     logger.log('[local-cdn-plugin]: Initializing local CDN plugin')
 
-    const cdnPlugins = localCdnPlugin({
-      localCdnConfig: engineConfig.localCdnConfig,
+    const importMapPlugins = importMapLocalPlugin({
+      importMapLocalConfig: engineConfig.importMapLocalConfig,
       base: getBaseUrlFromCli(config.base),
       cdnDir: VITE_LOCAL_BUNDLE_PATH
     })
 
-    if (cdnPlugins && cdnPlugins.length > 0) {
-      config.plugins.push(...cdnPlugins)
+    if (importMapPlugins && importMapPlugins.length > 0) {
+      config.plugins.push(...importMapPlugins)
     }
   }
 

…onfig/src/localCdnFile/localCdnPlugin.js …src/localCdnFile/importMapLocalPlugin.jspackages/build/vite-config/src/localCdnFile/localCdnPlugin.js renamed to packages/build/vite-config/src/localCdnFile/importMapLocalPlugin.js packages/build/vite-config/src/localCdnFile/localCdnPlugin.js renamed to packages/build/vite-config/src/localCdnFile/importMapLocalPlugin.js

@@ -25,6 +25,15 @@ const defaultCopyConfig = {
 
 /**
  * 从importMapUrl字符串中提取包名、版本和文件路径
+ * ${versionDelimiter} 和 ${fileDelimiter} 是默认的 importMapUrl 中的占位符，
+ * 例如：
+ * importMapUrl = '${VITE_CDN_DOMAIN}/${packageName}${versionDelimiter}${version}${fileDelimiter}${filePath}'
+ * 提取的信息对象：
+ * {
+ *   packageName: '${packageName}',
+ *   version: '${version}',
+ *   filePathInPackage: '${filePath}'
+ * }
  * @param {string} str - 导入字符串
  * @returns {Object} - 提取的信息对象
  * @returns {string} packageName - 包名
@@ -43,7 +52,7 @@ function extractInfo(str) {
       filePathInPackage: filePath || '/'
     }
   } catch (error) {
-    logger.error(`[local-cdn-plugin]: Failed to extract info from ${str} 提取 importMap 信息失败`, error)
+    logger.error(`[import-map-local-plugin]: Failed to extract info from ${str} 提取 importMap 信息失败`, error)
   }
 }
 
@@ -130,22 +139,41 @@ function getCdnPathNpmInfo(
 /**
  * 本地化CDN插件
  * @param {Object} options - 配置选项
- * @param {Object} options.localCdnConfig - 本地CDN配置
- * @param {Object} options.localCdnConfig.importMap - 导入映射配置，定义需要本地化的CDN依赖
- * @param {Object} options.localCdnConfig.copy - 自定义复制配置，可以覆盖特定包的默认配置
+ * @param {Object} options.importMapLocalConfig - 本地CDN配置
+ * @param {Object} options.importMapLocalConfig.importMap - 导入映射配置，定义需要本地化的CDN依赖
+ * @param {Object} options.importMapLocalConfig.copy - 自定义复制配置，可以覆盖特定包的默认配置
  * @param {string} options.base - 构建的base URL
  * @param {string} options.cdnDir - 构建目录中的CDN文件夹名称
  * @param {string} options.bundleTempDir - 临时存放下载的包的目录
  * @returns {Array} - Vite插件数组
  */
-export function localCdnPlugin({
-  localCdnConfig = { importMap: { imports: {} }, copy: {} },
+export function importMapLocalPlugin({
+  importMapLocalConfig = { importMap: { imports: {} }, copy: {} },
   base = './',
   cdnDir = 'local-cdn-static', // 构建目录中的CDN文件夹名称
   bundleTempDir = 'bundle-deps/local-cdn' // 临时存放下载的包的目录
 }) {
-  const importMapConfig = localCdnConfig.importMap || { imports: {} }
-  const copyConfig = localCdnConfig.copy || {}
+  let importMapConfig = importMapLocalConfig.importMap
+
+  if (!importMapConfig || typeof importMapConfig !== 'object') {
+    logger.warn('[import-map-local-plugin]: Invalid importMapLocalConfig, using defaults')
+
+    importMapConfig = { imports: {}, copy: {} }
+  }
+
+  if (!importMapConfig.imports || typeof importMapConfig.imports !== 'object') {
+    logger.warn('[import-map-local-plugin]: Invalid importMapConfig, using defaults')
+
+    importMapConfig.imports = {}
+  }
+
+  if (!importMapConfig.copy || typeof importMapConfig.copy !== 'object') {
+    logger.warn('[import-map-local-plugin]: Invalid copyConfig, using defaults')
+
+    importMapConfig.copy = {}
+  }
+
+  const copyConfig = importMapConfig.copy || {}
   const defaultImportMapConfig = JSON.parse(
     fs.readFileSync(path.resolve(process.cwd(), './node_modules/@opentiny/tiny-engine/dist/import-map.json'), 'utf-8')
   )
@@ -157,7 +185,7 @@ export function localCdnPlugin({
   const combinedImportMapConfig = [...overriddenImportMap, ...parsedImportMapConfig]
 
   if (combinedImportMapConfig.length === 0) {
-    logger.warn('[local-cdn-plugin]: No CDN dependencies found or configured')
+    logger.warn('[import-map-local-plugin]: No CDN dependencies found or configured')
     return []
   }
   const combinedCopyConfig = { ...defaultCopyConfig, ...copyConfig }
@@ -181,9 +209,9 @@ export function localCdnPlugin({
 
   // 日志一下将要处理的内容
   logger.log(
-    `[local-cdn-plugin]: Processing ${combinedImportMapConfig.length} CDN dependencies to local directory: ${cdnDir}`
+    `[import-map-local-plugin]: Processing ${combinedImportMapConfig.length} CDN dependencies to local directory: ${cdnDir}`
   )
-  logger.log(`[local-cdn-plugin]: Need to install ${packageNeedToInstall.length} packages`)
+  logger.log(`[import-map-local-plugin]: Need to install ${packageNeedToInstall.length} packages`)
 
   const targetFiles = dedupeCopyFiles(cdnFiles)
   // 返回插件数组

packages/build/vite-config/src/localCdnFile/index.js

@@ -4,4 +4,4 @@ export * from './copyPreviewImportMap.js'
 export * from './utils.js'
 export * from './locateCdnNpmInfo.js'
 export * from './replaceImportPath.mjs'
-export * from './localCdnPlugin.js'
+export * from './importMapLocalPlugin.js'

packages/build/vite-config/src/vite-plugins/cdnCopyPlugin.js

@@ -69,8 +69,6 @@ async function copyFileOrDirectory(srcPath, destPaths, copiedFiles, outDir) {
       // 确保目标目录存在
       await fs.ensureDir(path.dirname(fullDestPath))
 
-      logger.log(`[vite-cdn-copy-plugin]: Copying from ${srcPath} to ${fullDestPath}`)
-
       if (isDirectory) {
         // 如果是目录，使用 fast-glob 遍历所有文件并处理
         logger.log(`[vite-cdn-copy-plugin]: Copying directory recursively: ${srcPath} -> ${fullDestPath}`)
@@ -99,8 +97,6 @@ async function copyFileOrDirectory(srcPath, destPaths, copiedFiles, outDir) {
 
         await copyFile(srcPath, finalDestPath)
       }
-
-      logger.log(`[vite-cdn-copy-plugin]: Successfully copied: ${srcPath} -> ${fullDestPath}`)
     } catch (err) {
       logger.error(`[vite-cdn-copy-plugin]: Failed to copy ${srcPath} to ${fullDestPath}`, err)
     }