monaco-editor-nls-adapter 1.0.1 → 2.1.0

package/README.md

@@ -13,10 +13,26 @@ Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted). Bridge the g
 
 - **Self-hosted Locales**: No external CDN dependencies; all language data is bundled locally.
 - **Monaco 0.50.0+ Ready**: Fully compatible with the latest internal NLS signatures of Monaco Editor.
-- **Zero-Config Lazy Loading**: Support for asynchronous initialization with Webpack/Vite chunk splitting.
+- **SourceMap Support**: Powered by `magic-string` for accurate source-to-bundle mapping.
+- **Ultra-Optimized (Mini & Lite)**:
+  - **JSON Minification**: All locale files are pre-minified, reducing the stat size by ~15%.
+  - **Slim/Lite Export**: Use `./lite` for a zero-bloat experience with no dynamic scanning.
 - **TypeScript Support**: First-class TS definitions for an excellent developer experience.
-- **Smart Detection**: Automatically detect browser language or manually switch as needed.
+- **Flexible API**: Advanced interfaces like `getCurrentLocale` and `setMessages` (custom data).
 - **Cross-Bundler**: Native support for **Webpack** (Loader) and **Vite/Rollup** (Plugin).
+- **Zero Configuration**: Automatic detection of `pnpm` and monorepo paths out of the box.
+- **Ultra-lightweight**: Redundant test files removed for even faster installation.
+
+## 📦 Supported Frameworks
+
+This adapter is compatible with all modern frontend frameworks:
+
+- **Vue 2**: Seamless integration with Vue CLI and Webpack projects.
+- **Vue 3**: Full support for Vite and Vue CLI configurations.
+- **React**: Compatible with native React apps and `@monaco-editor/react` (supports disabling CDN).
+- **Angular**: Compatible with Angular CLI (Webpack/Vite) build environments.
+- **SSR Frameworks**: Ready for **Next.js** and **Nuxt** server-side rendering environments.
+- **Universal**: Theoretically supports any web project built with **Webpack**, **Vite**, or **Rollup**.
 
 ## 🚀 Installation
 
@@ -31,16 +47,23 @@ npm install monaco-editor-nls-adapter
 In your `webpack.config.js`, add the adapter's loader to process Monaco Editor's ESM files.
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   module: {
     rules: [
       {
         test: /\.js$/,
-        // Crucial: Only process monaco-editor core files to avoid side effects
-        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        // Crucial: Only process monaco-editor ESM files
+        include: /monaco-editor[\\/]esm/,
         use: [
           {
-            loader: 'monaco-editor-nls-adapter/loader'
+            loader: loader,
+            options: {
+              // Optional: Custom monaco path fragment
+              // Detected automatically in most project structures (npm, pnpm, yarn)
+              // monacoPath: 'monaco-editor/esm'
+            }
           }
         ]
       }
@@ -54,15 +77,17 @@ module.exports = {
 For projects using Vue CLI, you can configure the loader via `chainWebpack`:
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   chainWebpack: config => {
     config.module
       .rule('monaco-editor-nls')
       .test(/\.js$/)
-      .include.add(/node_modules[\\/]monaco-editor[\\/]esm/)
+      .include.add(/monaco-editor[\\/]esm/)
       .end()
       .use('nls-loader')
-      .loader('monaco-editor-nls-adapter/loader')
+      .loader(loader)
       .end();
   }
 };
@@ -74,50 +99,86 @@ In your `vite.config.js` or `vite.config.ts`:
 
 ```javascript
 import { defineConfig } from 'vite';
-import monacoNlsPlugin from 'monaco-editor-nls-adapter/vite-plugin';
+import { vitePlugin } from 'monaco-editor-nls-adapter';
 
 export default defineConfig({
   plugins: [
-    monacoNlsPlugin()
+    vitePlugin({
+      // Optional: Custom monaco path fragment
+      // Automatically detected (works with pnpm and monorepos)
+      // monacoPath: 'monaco-editor/esm'
+    })
   ]
 });
 ```
 
+### 4. Bundle Optimization (Optional)
+
+If you are concerned about bundle size or the "Stat size" reported by bundle analyzers, you can use the **Lite Version**. 
+
+The default entry point uses dynamic `require`/`import` with template strings, which may cause build tools (Webpack/Vite) to scan and include all available locales or report a large "original size." The Lite version eliminates this by providing only the core logic.
+
+```javascript
+// 1. Import from /lite
+import { setMessages } from 'monaco-editor-nls-adapter/lite';
+
+// 2. Manually import ONLY the language you need
+import zhHans from 'monaco-editor-nls-adapter/locales/zh-hans.json';
+
+// 3. Initialize BEFORE monaco-editor loads
+setMessages(zhHans, 'zh-hans');
+
+// 4. Import monaco-editor as usual
+import * as monaco from 'monaco-editor';
+```
+
 ## 📖 Usage
 
 ### Initialization
 
 Call `init` or `initAsync` **before** importing `monaco-editor` or creating any editor instances.
 
-```typescript
 import * as nlsAdapter from 'monaco-editor-nls-adapter';
 
-/**
- * Option 1: Synchronous (Standard)
- * Recommended for small clusters or if you don't mind the initial bundle size.
- */
+// 1. Synchronous (Standard)
 nlsAdapter.init('zh-hans');
 
-/**
- * Option 2: Asynchronous (Performance Optimization)
- * Leverages Webpack/Vite dynamic imports for code splitting.
- */
+// 2. Asynchronous (Code Splitting)
 // await nlsAdapter.initAsync('zh-hans');
 
-/**
- * Option 3: Automatic Browser Detection
- */
-// nlsAdapter.init(); // Sync
-// await nlsAdapter.initAsync(); // Async
-
-import * as monaco from 'monaco-editor';
+// 3. Get current locale
+console.log(nlsAdapter.getCurrentLocale()); // 'zh-hans'
 
-monaco.editor.create(document.getElementById('container'), {
-  value: 'console.log("Hello Localization!");',
-  language: 'javascript'
+// 4. Custom Messages (Override built-in locales)
+/*
+nlsAdapter.setMessages({
+  'vs/editor/common/editorContextKeys': {
+    'editor.action.clipboardCopyAction': 'Copy (Custom)'
+  }
 });
+*/
+
+import * as monaco from 'monaco-editor';
+// ... create editor as usual
 ```
 
+### Framework Integration (React / Vue)
+
+This package works seamlessly with major frameworks. Special note for **React** (@monaco-editor/react): Make sure to use `loader.config({ monaco })` to disable CDN and map to your local, localized monaco instance.
+
+See: [Framework Integration Best Practices (Examples)](./examples/framework-integration.md)
+
+### API Reference
+
+| Function | Description |
+| --- | --- |
+| `init(locale?: string): boolean` | Synchronous initialization. **Note**: This will trigger the bundler to scan all locales in the directory. |
+| `initAsync(locale?: string): Promise<boolean>` | Asynchronous initialization with dynamic imports. |
+| `getCurrentLocale(): string` | Returns the currently active locale code. Returns `custom` if set via `setMessages`. |
+| `setMessages(data: object, locale?: string)` | Manually inject translations. Recommended with `./lite` for minimum footprint. |
+| `vitePlugin(options?: object)` | Vite plugin function. |
+| `loader: string` | Absolute path to the Webpack loader. |
+
 ## 🗂 Supported Locales
 
 | Code | Language |

package/README_zh.md

@@ -14,9 +14,26 @@
 - **自托管语言包**: 无需依赖外部 CDN；所有语言数据在本地打包。
 - **适配 Monaco 0.50.0+**: 完全兼容 Monaco Editor 最新的内部 NLS 调用签名。
 - **性能优化 (懒加载)**: 通过 Webpack/Vite 的动态导入实现按需分包加载。
+- **SourceMap 支持**: 基于 `magic-string` 实现转换后的精准还原，调试无忧。
+- **极致优化 (Mini & Lite)**: 
+  - **内置 JSON 压缩**: 所有语言包均已移除空格，Stat size 减少约 15%。
+  - **Slim/Lite 导出**: 提供 `./lite` 入口，不包含动态加载逻辑，可实现 **0 冗余** 打包。
 - **TypeScript 支持**: 完善的类型定义，为开发提供极佳的智能感知。
-- **智能语言识别**: 支持自动识别浏览器语言或手动切换。
+- **灵活的 API**: 提供 `getCurrentLocale` 和 `setMessages` (自定义数据) 等高级接口。
 - **跨构建工具支持**: 原生支持 **Webpack** (Loader) 以及 **Vite/Rollup** (Plugin)。
+- **智能路径探测**: 自动识别 `pnpm` 和 monorepo 路径，**零配置**即可使用。
+- **轻量化**: 移除了冗余测试文件，发布包体积进一步精简。
+
+## 📦 支持的框架
+
+本适配器与主流前端框架均可完美兼容：
+
+- **Vue 2**: 完美适配 Vue CLI 和 Webpack 项目。
+- **Vue 3**: 深度支持 Vite 和 Vue CLI 配置。
+- **React**: 适配原生 React 应用及 `@monaco-editor/react` (支持禁用 CDN)。
+- **Angular**: 支持 Angular CLI (Webpack/Vite) 构建环境。
+- **SSR 框架**: 兼容 **Next.js** 和 **Nuxt** 等服务端渲染环境。
+- **通用**: 理论上支持任何基于 **Webpack**、**Vite** 或 **Rollup** 构建的 web 项目。
 
 ## 🚀 安装
 
@@ -31,16 +48,23 @@ npm install monaco-editor-nls-adapter
 在 `webpack.config.js` 中，添加此适配器的 loader 来处理 Monaco Editor 的 ESM 源码。
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   module: {
     rules: [
       {
         test: /\.js$/,
-        // 重要：仅处理 monaco-editor 的 esm 目录，避免对业务代码产生副作用
-        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        // 重要：仅处理 monaco-editor 的 esm 目录
+        include: /monaco-editor[\\/]esm/,
         use: [
           {
-            loader: 'monaco-editor-nls-adapter/loader'
+            loader: loader,
+            options: {
+              // 可选：自定义 monaco 路径片段
+              // 插件会自动探测 node_modules 下的 monaco-editor/esm，通常无需配置
+              // monacoPath: 'monaco-editor/esm'
+            }
           }
         ]
       }
@@ -54,15 +78,17 @@ module.exports = {
 对于使用 Vue CLI 的项目，建议使用 `chainWebpack` 进行配置：
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   chainWebpack: config => {
     config.module
       .rule('monaco-editor-nls')
       .test(/\.js$/)
-      .include.add(/node_modules[\\/]monaco-editor[\\/]esm/)
+      .include.add(/monaco-editor[\\/]esm/)
       .end()
       .use('nls-loader')
-      .loader('monaco-editor-nls-adapter/loader')
+      .loader(loader)
       .end();
   }
 };
@@ -74,50 +100,86 @@ module.exports = {
 
 ```javascript
 import { defineConfig } from 'vite';
-import monacoNlsPlugin from 'monaco-editor-nls-adapter/vite-plugin';
+import { vitePlugin } from 'monaco-editor-nls-adapter';
 
 export default defineConfig({
   plugins: [
-    monacoNlsPlugin()
+    vitePlugin({
+      // 可选：自定义 monaco 路径片段
+      // 插件会自动探测物理路径（支持 pnpm），通常无需配置
+      // monacoPath: 'monaco-editor/esm'
+    })
   ]
 });
 ```
 
+### 4. 极致体积优化 (可选)
+
+如果你对打包后的 JS 文件体积非常敏感，或者 bundle analyzer 显示 `monaco-editor-nls-adapter` 的 `Stat size` 过大（这是由于默认入口包含所有语言包的动态引用导致的），可以使用 **Lite 版本**。
+
+Lite 版本不具备内置的语言包发现逻辑，需要你手动导入所需的语言 JSON。这样构建工具（Webpack/Vite）只会打包你真正使用的那门语言，而不会扫描整个 `./locales` 目录。
+
+```javascript
+// 1. 从 /lite 入口导入
+import { setMessages } from 'monaco-editor-nls-adapter/lite';
+
+// 2. 手动导入特定的语言 JSON (由你自己决定包含哪门语言)
+import zhHans from 'monaco-editor-nls-adapter/locales/zh-hans.json';
+
+// 3. 初始化 (必须要在 monaco 加载前运行)
+setMessages(zhHans, 'zh-hans');
+
+// 4. 正常使用 monaco-editor
+import * as monaco from 'monaco-editor';
+```
+
 ## 📖 使用指南
 
 ### 初始化
 
 在导入 `monaco-editor` 或创建任何实例**之前**，先调用 `init` 或 `initAsync`。
 
-```typescript
 import * as nlsAdapter from 'monaco-editor-nls-adapter';
 
-/**
- * 方式 1: 同步初始化 (标准用法)
- * 适用于语言包体量较小，或不介意首屏全量包含翻译数据的场景。
- */
+// 1. 同步初始化 (标准用法)
 nlsAdapter.init('zh-hans');
 
-/**
- * 方式 2: 异步初始化 (性能优化推荐)
- * 利用 Webpack/Vite 的动态 import 实现分包，仅加载当前所需语言。
- */
+// 2. 异步初始化 (分包懒加载)
 // await nlsAdapter.initAsync('zh-hans');
 
-/**
- * 方式 3: 自动识别浏览器语言
- */
-// nlsAdapter.init(); // 同步
-// await nlsAdapter.initAsync(); // 异步
-
-import * as monaco from 'monaco-editor';
+// 3. 获取当前语言
+console.log(nlsAdapter.getCurrentLocale()); // 'zh-hans'
 
-monaco.editor.create(document.getElementById('container'), {
-  value: 'console.log("Hello Localization!");',
-  language: 'javascript'
+// 4. 使用自定义翻译数据 (不使用内置语言包)
+/*
+nlsAdapter.setMessages({
+  'vs/editor/common/editorContextKeys': {
+    'editor.action.clipboardCopyAction': '复制 (Custom)'
+  }
 });
+*/
+
+import * as monaco from 'monaco-editor';
+// ... 之后正常创建编辑器
 ```
 
+### 框架集成 (React / Vue)
+
+本项目与主流框架完美配合。特别注意：若使用 **React** (@monaco-editor/react)，请务必通过 `loader.config({ monaco })` 禁用 CDN 并映射到本地实例。
+
+详细的框架集成指南请参考：[框架集成最佳实践 (Examples)](./examples/framework-integration.md)
+
+### API 详述
+
+| 函数 | 说明 |
+| --- | --- |
+| `init(locale?: string): boolean` | 同步初始化。如果不传参数，尝试探测浏览器语言。注意：此方法会导致构建工具引入全量语言包（或触发全量扫描）。 |
+| `initAsync(locale?: string): Promise<boolean>` | 异步初始化。利用动态 import 拆分语言包。 |
+| `getCurrentLocale(): string` | 获取当前已生效的语言代码。如果是自定义数据，返回 `custom`。 |
+| `setMessages(data: object, locale?: string)` | 手动注入翻译字典。建议配合 `./lite` 入口使用以优化体积。 |
+| `vitePlugin(options?: object)` | Vite 插件函数。 |
+| `loader: string` | Webpack Loader 的绝对路径。 |
+
 ## 🗂 支持的语言列表
 
 | 语言代码 | 对应语言 |

package/index.d.ts

@@ -1,16 +1,5 @@
-export interface NLSProxy {
-  localize(path: string, data: any, defaultMessage: string, ...args: any[]): string;
-  localize2(path: string, data: any, defaultMessage: string, ...args: any[]): { value: string; original: string };
-  setLocaleData(data: Record<string, any>): void;
-  getConfiguredDefaultLocale(): string | undefined;
-  loadMessageBundle(file: string): (path: string, data: any, defaultMessage: string, ...args: any[]) => string;
-  config(opt: any): (file: string) => any;
-  create(key: string, data: any): {
-    localize: (idx: any, defaultValue: string, ...args: any[]) => string;
-    localize2: (idx: any, defaultValue: string, ...args: any[]) => { value: string; original: string };
-    getConfiguredDefaultLocale: () => string | undefined;
-  };
-}
+import { NLSProxy } from './proxy';
+import monacoNlsPlugin from './vite-plugin';
 
 /**
  * 支持的语言代码类型
@@ -21,18 +10,53 @@ export type LocaleCode =
 
 /**
  * 初始化 Monaco Editor 的语言包
- * @param locale 语言代码，如 'zh-hans'。如果不传，将尝试检测浏览器语言。
+ * @param locale 语言代码，如 'zh-hans'
+ * @param force 是否强制重新初始化
+ * @returns 是否加载成功
  */
-export function init(locale?: LocaleCode | string): void;
+export function init(locale?: LocaleCode | string, force?: boolean): boolean;
 
 /**
  * 异步初始化 Monaco Editor 的语言包
- * 使用动态 import()，支持 Webpack 分包和懒加载。
  * @param locale 语言代码
+ * @param force 是否强制重新加载
+ * @returns 是否加载成功
  */
-export function initAsync(locale?: LocaleCode | string): Promise<void>;
+export function initAsync(locale?: LocaleCode | string, force?: boolean): Promise<boolean>;
 
 /**
- * NLS 代理对象，由 loader 注入到 Monaco 源码中
+ * 获取当前已生效的语言代码名称
+ */
+export function getLocaleName(): string;
+
+/**
+ * 获取当前加载的原始翻译数据
+ */
+export function getLocaleData(): Record<string, any> | null;
+
+/**
+ * 手动设置翻译数据字典
+ * @param messages 符合 Monaco NLS 格式的 JSON 对象
+ * @param locale 语言代码 (可选标识符)
+ */
+export function setMessages(messages: Record<string, any>, locale?: string): void;
+
+/**
+ * NLS 代理对象声明
  */
 export const proxy: NLSProxy;
+
+/**
+ * Vite 插件导出
+ */
+export const vitePlugin: typeof monacoNlsPlugin;
+
+/**
+ * Webpack Loader 绝对路径导出 (用于 webpack.config.js)
+ */
+export const loader: string;
+
+// 重新导出子模块中的类型，方便从主模块引用
+export { NLSProxy } from './proxy';
+export { PluginOptions } from './vite-plugin';
+export { transform } from './transform';

package/index.js

@@ -1,4 +1,5 @@
-const proxy = require('./proxy')
+const lite = require('./lite')
+const proxy = lite.proxy
 
 /**
  * 语言映射字典，用于将常见的浏览器语言代码还原为本包中支持的代码。
@@ -11,63 +12,99 @@ const LOCALE_MAP = {
   'zh-hk': 'zh-hant',
   'en-us': 'en',
   'en-gb': 'en',
-  'en': 'en'
+  'en': 'en',
+  'ja-jp': 'ja',
+  'ja': 'ja',
+  'ko-kr': 'ko',
+  'ko': 'ko',
+  'de-de': 'de',
+  'de': 'de',
+  'fr-fr': 'fr',
+  'fr': 'fr',
+  'es-es': 'es',
+  'es': 'es',
+  'it-it': 'it',
+  'it': 'it',
+  'ru-ru': 'ru',
+  'ru': 'ru',
+  'pt-br': 'pt-br'
 }
 
+let IS_LOADING = false
+
 /**
  * 使用指定的语言代码初始化 Monaco Editor 的本地化。
- * 此方法会从本地 /locales 目录加载 JSON 数据。
- * @param {string} locale 语言代码 (例如 'zh-hans', 'ja', 'ko')。如果不传，将尝试检测浏览器语言。
+ * 此方法使用同步 require，会触发构建工具打包所有相关 JSON。
+ * @param {string} locale 语言代码
+ * @param {boolean} force 是否强制重新初始化
  */
-function init(locale) {
-  // 如果没有传递 locale，尝试从浏览器环境获取
-  if (!locale && typeof navigator !== 'undefined') {
+function init(locale, force = false) {
+  const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
+  if (!locale && isBrowser) {
     locale = navigator.language || navigator.userLanguage
   }
 
-  // 小写化并查找映射
   let targetLocale = (locale || 'zh-hans').toLowerCase()
   if (LOCALE_MAP[targetLocale]) {
     targetLocale = LOCALE_MAP[targetLocale]
   }
 
+  if (lite.getCurrentLocale() === targetLocale && !force) {
+    return true
+  }
+
   try {
+    // 这里的动态 require 是导致全量打包的主要原因，若需精简请改用 lite.setMessages()
     const data = require(`./locales/${targetLocale}.json`)
-    proxy.setLocaleData(data)
+    lite.setMessages(data, targetLocale)
+    return true
   } catch (e) {
-    console.error(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}。回退到默认设置。`, e)
+    if (isBrowser) {
+      console.warn(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}`, e)
+    }
+    return false
   }
 }
 
 /**
- * 异步初始化 Monaco Editor 的本地化。
- * 使用动态 import()，允许 Webpack 将语言包拆分为独立的 chunk，实现按需加载。
- * @param {string} locale 语言代码。如果不传，将尝试检测浏览器语言。
- * @returns {Promise<void>}
+ * 异步加载语言包。
+ * @param {string} locale 语言代码
+ * @param {boolean} force 是否强制重新初始化
  */
-async function initAsync(locale) {
-  // 如果没有传递 locale，尝试从浏览器环境获取
-  if (!locale && typeof navigator !== 'undefined') {
+async function initAsync(locale, force = false) {
+  const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
+  if (!locale && isBrowser) {
     locale = navigator.language || navigator.userLanguage
   }
 
-  // 小写化并查找映射
   let targetLocale = (locale || 'zh-hans').toLowerCase()
   if (LOCALE_MAP[targetLocale]) {
     targetLocale = LOCALE_MAP[targetLocale]
   }
 
+  if (lite.getCurrentLocale() === targetLocale && !force) {
+    return true
+  }
+
+  if (IS_LOADING && !force) return false
+  IS_LOADING = true
+
   try {
-    // 使用动态 import 实现懒加载
-    const module = await import(`./locales/${targetLocale}.json`)
-    proxy.setLocaleData(module.default || module)
+    const module = await import(/* webpackChunkName: "nls-[request]" */ `./locales/${targetLocale}.json`)
+    lite.setMessages(module.default || module, targetLocale)
+    return true
   } catch (e) {
-    console.error(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}。`, e)
+    if (isBrowser) {
+      console.warn(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}`, e)
+    }
+    return false
+  } finally {
+    IS_LOADING = false
   }
 }
 
 module.exports = {
+  ...lite,
   init: init,
-  initAsync: initAsync,
-  proxy: proxy
+  initAsync: initAsync
 }

package/lite.js

@@ -0,0 +1,27 @@
+const proxy = require('./proxy')
+
+/**
+ * 获取当前已生效的语言代码
+ */
+function getCurrentLocale() {
+  return proxy.getLocaleName()
+}
+
+/**
+ * 手动设置翻译数据字典
+ * @param {Object} data 符合 Monaco NLS 格式的 JSON 对象
+ * @param {string} locale 语言代码标识 (可选)
+ */
+function setMessages(data, locale = 'custom') {
+  proxy.setLocaleData(data, locale)
+}
+
+module.exports = {
+  getCurrentLocale: getCurrentLocale,
+  setMessages: setMessages,
+  setLocaleData: proxy.setLocaleData,
+  proxy: proxy,
+  // 插件导出 (仍保留，以便用户可以从 lite 引用所有工具)
+  vitePlugin: require('./vite-plugin'),
+  loader: __dirname + '/loader.js'
+}

package/loader.js

@@ -4,8 +4,27 @@ const { transform } = require('./transform')
  * Webpack Loader for Monaco Editor NLS Adapter
  */
 module.exports = function (source) {
+  // 极致性能优化：第一层极速过滤
+  if (!this.resourcePath.endsWith('.js') || this.resourcePath.indexOf('monaco-editor') === -1) {
+    return source
+  }
+
   if (this.cacheable) this.cacheable()
   
+  // 获取 loader options
+  const options = (typeof this.getOptions === 'function') ? this.getOptions() : this.query
+  
   // 使用共享的 transform 逻辑
-  return transform(source, this.resourcePath)
+  const result = transform(source, this.resourcePath, options || {})
+  
+  // 如果返回包含 SourceMap 的对象，则使用 this.callback 提示 Webpack
+  if (result && typeof result === 'object') {
+    if (this.callback) {
+      this.callback(null, result.code, result.map)
+      return
+    }
+    return result.code
+  }
+
+  return result
 }