于是对意外进行了反复测验，发现在某些环境下（ img 使用缓存到本地资源的图像作为源时）出现的频率较高。

而这导致了我本以 img 元素加载图像作为契机执行的想法成了不可执行事件。

import { useState } from 'react';

export function Img({ src }: {src: string}) {
  const [loaded, setLoaded] = useState(false);

  const handleLoad = () => {
    setLoaded(true);
  }


  return (
  <img src={src}
    onload={handleLoad}
    className={loaded ? styles.loaded ? style.loading}
  />
  );
}

病症​

原因是由于在 react 从虚拟 DOM 转化为实际的 DOM 时，先建立 DOM （通过 ReactDOM.render）后进行事件监听（通过 listenToAllSupportedEvents 注册所有可冒泡事件到事件池）及通过 listenToNonDelegatedEvent 未无法冒泡的事件的监听。

而无法冒泡的事件的监听，需要等到整个 DocumentFragment 挂载后才会进行监听，而此时已然错过了由于加载缓存资源而同步触发 load 事件。

开方​

既然无法在 img 元素节点 load 时加载状态，那么只能验证其是否加载（ img 元素节点的 HTMLImageElement.complete 属性）而判定元素是否已经触发load（但这样会增加额外的工作量）。

import React, { useState, useRef, useEffect } from 'react';

export function Img({ src }: { src: string }) {
  const imgRef = useRef<HTMLImageElement>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  useEffect(() => {
    const img = imgRef.current;
    if (!img) return; // 未加载
    // 在刚初始化完成后图像资源已经加载完毕，那么直接更新状态而无需对 load 事件进行处理
    if (img.complete && img.naturalHeight !== 0) {
      setIsLoaded(true);
      return;
    }
    const handleLoad = () => setIsLoaded(true); // 处理句柄
    img.addEventListener('load', handleLoad); // 注册 load 事件
    // 清理监听事件
    return () => img.removeEventListener('load', handleLoad);
  }, [src]);

  return (
    <img
      ref={imgRef}
      alt={'一张图片'}
      src={src}
      className={isLoaded ? 'block' : 'none'}
    />
  );
}

多使用了 useEffect、useRef Hooks ，在性能上肯定有轻微的影响，但是这确实处理该问题的良策。

一、正确的 scss 配置​

使用 node-sass 或 sass 包处理 scss 后缀文件的编译，而负责链接 sass 和 rollup 的是 rollup-plugin-postcss 或 rollup-plugin-styles。但是 rollup-plugin-styles 的下载量远远低于 rollup-plugin-postcss （尽然，单纯的下载量说明不了什么问题）。

好了，现在以 rollup-plugin-postcss 为例。

1. 引入 npm 包​

# 安装主要依赖
npm install --save-dev rollup rollup-plugin-postcss \
     autoprefixer cssnano
# 安装 scss 支持
npm install --save-dev node-sass # 或 sass

2. 配置​

import
import postcss from 'rollup-plugin-postcss';
import autoprefixer from 'autoprefixer';
import cssnano from 'cssnano';


export default {
    // ... 其他配置
    plugin: [
        // ... 其他插件
    postcss({
      // 关键配配置：提取独立 CSS 文件
      // extract: true, // 移除该项则默认内联
      extract: 'component.css', // 移除该项则默认内联
      // 支持 .scss 编译
      extensions: ['.css', '.scss'],
      // 开启 CSS 源码映射
      sourceMap: true,
      // 生产环境：压缩 CSS + 自动补全前缀
      plugins: [
        autoprefixer({
          overrideBrowserslist: ['> 1%', 'last 2 versions'], // 浏览器兼容
        }),
        cssnano(), // 压缩 CSS （取出空格、合并规则）
      ],
      modules: {
        generateScopedName: '[name]__[local]', // CSS Modules 命名规则
        // 如果你的类型中有用下划线连字符的，建议关闭下面的配置，因为它会转化为驼峰而导致下划线丢失
        // localsConvention: 'camelCaseOnly', // 导出的类名格式
      },
      // 可选：自定义 scss 编译选项
      scss: {
        loadPaths: ['node_modules'],
        quietDeps: true,
        verbose: true,
      },
    }),
        // ... 其他插件
    ]
    // ... 其他配置
}

3. 使用​

需要显式的使用 ~ 标识启用者来自于 "node_modules" 才可以。

// 即便是 `enr` 包导出为 "enr/common.scss" ，也必须使用完整路径 "enr/styles/common.scss"
import '~enr/styles/common.scss';

二、其他包​

1. 模块解析​

使用包 @rollup/plugin-node-resolve 解析 node_modules 路径（含 .ts/.scss 文件）

2. 资源预处理​

使用包 @rollup/plugin-url 处理 JS 中的图片/字体资源（替代为 data URL ），需要在 babel/commonjs 前导入语句避免被修改

3. Typescript​

官方推荐使用 @rollup/plugin-typescript ，但是该包在 pnpm 的 workspace 子包使用中无法找到子包自身的 "tsconfig.json" 文件。可能是我配置的问题，但是目前使用 rollup-plugin-typescript2 代替，必须放在 commonjs/babel 之前。

@rollup/plugin-typescript: Path of Typescript
    compiler option 'outDir' must be located
    inside Rollup 'dir' option.

4. JSON​

使用包 @rollup/plugin-json 将 JSON 转化为 ES 模块，需放在 commonjs 之前，避免被误处理。

5. CommonJS 依赖​

使用包 [@rollup/plugin-commonjs] 处理 node_modules 中的 CommonJS 依赖。

6. babel​

使用包 @rollup/plugin-babel 进行 JS 语法的转义/polyfill （处理所有的 JS 代码，包含 TS 转义结果）。

7. scss​

使用 rollup-plugin-postcss 处理 .css/.scss 文件，放在 babel 后面更安全

8. 简单配置​

import { preserveDirective } from '@qqi/rollup-preserve-directive';
import resolve from '@rollup/plugin-node-resolve';
import url from '@rollup/plugin-url';
import typescript from '@rollup/plugin-typescript';
import json from '@rollup/plugin-json';
import commonjs from '@rollup/plugin-commonjs';
import babel from '@rollup/plugin-babel';
import postcss from 'rollup-plugin-postcss';
import autoprefixer from 'autoprefixer';
import cssnano from 'cssnano';
import copy from 'rollup-plugin-copy';

export default {
  // ... 其他配置
  plugins: [
    preserveDirective(), // 保留 'use client'; 指令
    resolve({
      extensions: ['.js', '.ts', '.jsx', '.tsx', '.scss', '.css'],
    }),
    url({
      // 将小于 8 kb 的文件内联为 base64 编码
      limit: 8 * 1024, // 8 kb
      include: ['**/*.png'], // 只处理 png 文件
      emitFiles: true, // 发出文件而不是将其转化为 base6
      fileName: '[name][hash].[ext]', // 输出的格式
    }),
    typescript({
      tsconfig: './tsconfig.json',
    }),
    json(),
    commonjs(), // 处理 CommonJs 模块转化为 ES 模块
    babel({
      extends: ['.js', '.jsx', '.ts', '.tsx'],
      babelHelpers: 'runtime', // 关键： 使用 @babel/runtime
      include: ['src/**/*'], // 确保包含所有的源文件
      exclude: 'node_modules/**',
      skipPreflightCheck: true,
      presets: [
        ['@babel/preset-env', { modules: false }],
        '@babel/preset-react',
        '@babel/preset-typescript',
      ],
    }),
    postcss({
      // 关键配配置：提取独立 CSS 文件
      // extract: true, // 移除该项则默认内联
      extract: 'component.css', // 移除该项则默认内联
      // 支持 .scss 编译
      extensions: ['.css', '.scss'],
      // 开启 CSS 源码映射
      sourceMap: true,
      // 生产环境：压缩 CSS + 自动补全前缀
      plugins: [
        autoprefixer({
          overrideBrowserslist: ['> 1%', 'last 2 versions'], // 浏览器兼容
        }),
        cssnano(), // 压缩 CSS （取出空格、合并规则）
      ],
      modules: {
        generateScopedName: '[name]__[local]', // CSS Modules 命名规则
        localsConvention: 'camelCaseOnly', // 导出的类名格式
      },
      // 可选：自定义 scss 编译选项
      scss: {
        loadPaths: ['node_modules'],
        quietDeps: true,
        verbose: true,
      },
    }),
    copy({ targets: [{ src: 'src/css/**', dest: 'dist/' }] }),
  ],
  // ... 其他配置
};

三、实用包​

• 高频使用：
  • @rollup/plugin-replace ： 环境变量替换
  • rollup-plugin-dts ： 生成纯净的 .d.ts 声明文件
  • @rollup/plugin-terser ： 官方维护的代码压缩
  • rollup-plugin-visualizer ： Bundle 体积可视化分析
• 开发体验增强：
  • rollup-plugin-delete ： 构建前自动清理 dist 目录
  • @rollup/plugin-serve 和 rollup-plugin-livereload ： 本地开发服务器和热重载
  • @rollup/plugin-alias ： 路径别名
• 高级构建能力 ：
  • @rollup/plugin-html ： 自动生成 HTML 入口。复杂项目建议使用 rollup-plugin-html
  • @rollup/plugin-workbox ： PWA 支持：生成 Service worker
  • rollup-plugin-gzip/rollup-plugin-brotli ： 生成 .gz / .br 压缩资源，部署在 Nginx 时可直接提供预压缩版本
  • rollup-plugin-manifest ： 输出 manifest.json 资源映射， SSR 项目祝福资源时必备
  • rollup-plugin-license ： 自动生成第三方依赖许可汇总
• 特定技术栈利器 ：
  • @rollup/plugin-worker ： 自动打包 Worker 脚本并生成 URL
  • @rollup/plugin-wasm ： 处理 .wasm 模块的导入
  • @rollup/plugin-dynamic-import-vars ： 解析 import('.lang')
  • @rollup/plugin-inject ： 支持 process、Buffer 等 Node 全局对象（浏览器环境必备）

一、打包核心原理​

1. 入口分析与依赖图构建​

Rollup 从配置文件中 input 配置的入口文件开始，通过静态分析 ES 模块的 import/export 语句，递归遍历所有依赖模块，不会执行代码（这是 Tree Shaking 的基础），最终构建出一个「模块依赖图」，记录所有模块的依赖关系、导出内容、导入内容。

2. 插件生命周期执行（核心扩展点）​

Rollup 本身核心功能有限，所有自定义转换、路径解析、文件加载等能力都依赖插件。在打包的各个阶段，Rollup 会按顺序调用插件的钩子函数，对模块进行处理（这部分是实现你需求的核心）。

3. AST 解析与转换​

Rollup 内置 acorn 解析器，会将每个模块的代码解析为 ESTree 规范的抽象语法树（AST）。所有代码的修改、替换、移除，都不是直接操作字符串（易出错），而是通过操作 AST 节点实现的，修改完成后再将 AST 转换回可执行的 JS 代码。

4. 树摇（Tree Shaking）​

基于 ES 模块的「静态特性」（ import/export 只能在模块顶层，不能动态判断、不能嵌套在代码块中），Rollup 会分析模块依赖图，移除所有未被使用的导出内容和死代码，减少打包产物体积。你的需求 2、3 本质上是「增强版树摇」，需要自定义插件辅助实现。

5. 产物生成与输出​

根据配置文件 output 中的格式（ es/cjs/umd 等）、输出路径、拆分策略等，将处理后的所有模块合并，生成最终的打包文件，若配置了 sourcemap ，还会生成对应的源码映射文件。

二、插件工作原理​

1. 插件的本质​

Rollup 插件是一个「返回钩子对象的函数」，函数可以接收插件配置参数，返回的对象中包含了 Rollup 打包生命周期的各种钩子， Rollup 在对应阶段会自动调用这些钩子。

function customRollupPlugin(options = {}) {
  return {
    // 插件名称，用于报错信息和日志标识，必填
    name: 'custom-transform-plugin',
    // 各种生命周期钩子
    options(config) {
      /* 修改打包配置 */
    },
    resolveId(source) {
      /* 解析模块真实路径 */
    },
    transform(code, id) {
      /* 转换模块代码，核心实现需求 */
    },
    generateBundle(outputOptions, bundle) {
      /* 处理生成后的产物 */
    },
  };
}

2. 核心钩子​

• options ：打包开始前执行，用于修改 Rollup 原始配置（比如补充输出格式）。
• resolveId ：解析模块 ID（路径），用于处理别名、第三方包、虚拟模块（比如返回自定义模块 ID 屏蔽原始模块）。
• load ：根据模块 ID 加载模块内容，用于加载非 JS 文件、虚拟模块内容（比如返回自定义代码替换原始模块）。
• transform ：加载模块后、AST 分析前执行，接收模块代码和模块 ID，返回修改后的代码和 sourcemap。这是实现「代码转换 / 移除」的核心钩子，我们会在这里操作 AST 完成所有需求

3. 插件实现的核心技术​

要实现代码的精准转换 / 移除，不能直接用字符串替换（易出现边界错误，比如误匹配变量名），核心依赖 3 个工具库：

• estree-walker ：遍历 ESTree 规范的 AST 节点，方便找到需要修改 / 移除的节点。
• magic-string ：安全修改代码字符串，同时保留 sourcemap（避免打包后无法映射到源码，难以调试）。
• @rollup/pluginutils ：提供实用工具（比如 createFilter），用于过滤需要处理的文件（比如只处理 .js/.ts 文件，忽略 node_modules）

三、小插件： rollup 版移除打印狗​

1. 安装依赖​

# Rollup 内置，但单独安装可保证版本一致，用于解析代码为 AST
npm install --save-dev estree-walker magic-string @rollup/pluginutils acorn

2. 代码片段​

// 自定义 Rollup 插件：prod环境下代码转换与死代码移除
import acorn from 'acorn';
import { walk } from 'estree-walker';
import MagicString from 'magic-string';
import { createFilter } from '@rollup/pluginutils';

function prodCodeTransformPlugin(options = {}) {
  // 过滤需要处理的文件：默认处理 .js/.ts 文件，忽略 node_modules
  const filter = createFilter(
    options.include || ['**/*.js', '**/*.ts'],
    options.exclude || ['node_modules/**'],
  );

  // 判断是否为 production 环境
  const isProduction = process.env.NODE_ENV === 'production';

  return {
    name: 'qqi-rollup-plugin-remove-dog', // 插件名称，必填
    /**
     * 核心转换钩子：处理每个模块的代码
     * @param {string} code - 模块原始代码
     * @param {string} id - 模块 ID（文件路径）
     * @returns {object|void} - 修改后的代码和 sourcemap
     */
    transform(code, id) {
      // 1. 非 production 环境、无需处理的文件，直接返回
      if (!isProduction || !filter(id)) return;

      // 2. 初始化 MagicString，用于安全修改代码并保留 sourcemap
      const magicStr = new MagicString(code);
      // 3. 解析代码为 AST（ESTree 规范）
      let ast;
      try {
        ast = acorn.parse(code, {
          ecmaVersion: 'latest',
          sourceType: 'module', // 按 ES 模块解析
          ranges: true, // 保留节点的位置范围（start/end），方便 magicStr 操作
          locations: true,
        });
      } catch (err) {
        this.warn(`解析模块 ${id} 失败：${err.message}`);
        return;
      }

      // 标记：是否存在 dun = false（用于后续移除 if (dun) 代码块）
      let hasDunFalse = false;
      // 存储需要移除的代码节点范围（避免重复操作）
      const removeRanges = new Set();

      // 4. 遍历 AST，处理所有需求
      walk(ast, {
        // 进入 AST 节点时触发（核心处理逻辑）
        enter(node) {
          /************************** 需求 1：转换 Dog 导入 **************************/
          if (
            node.type === 'ImportDeclaration' &&
            node.source.value === '@qqi/log'
          ) {
            // 遍历 import 声明的所有命名导入
            node.specifiers.forEach(specifier => {
              // 匹配：import { Dog } from '@qqi/log'
              if (
                specifier.type === 'ImportSpecifier' &&
                specifier.imported.name === 'Dog'
              ) {
                // 找到 Dog 对应的代码起始和结束位置，替换为 DogVirtual
                const importedNameStart = specifier.imported.start;
                const importedNameEnd = specifier.imported.end;
                magicStr.overwrite(
                  importedNameStart,
                  importedNameEnd,
                  'DogVirtual',
                );
              }
            });
          }

          /************************** 需求 2：移除 dog 相关导入和调用 **************************/
          // 2.1 移除 import { dog } from 'xxx'
          if (node.type === 'ImportDeclaration') {
            let needRemoveImport = false;
            // 标记是否只导入了 dog（若有其他导入，只移除 dog 对应的部分）
            let onlyDogImport = node.specifiers.length === 1;

            node.specifiers.forEach((specifier, index) => {
              if (
                specifier.type === 'ImportSpecifier' &&
                specifier.imported.name === 'dog'
              ) {
                if (onlyDogImport) {
                  // 整个 import 语句都移除
                  removeRanges.add(`${node.start}-${node.end}`);
                  needRemoveImport = true;
                } else {
                  // 只移除 dog 对应的部分（处理逗号分隔）
                  const specStart = specifier.start;
                  const specEnd = node.specifiers[index + 1]
                    ? node.specifiers[index + 1].start - 1
                    : node.end;
                  removeRanges.add(`${specStart}-${specEnd}`);
                }
              }
            });

            // 若标记了移除整个 import，直接跳过后续处理
            if (needRemoveImport) return;
          }

          // 2.2 移除 dog('xxx')、dog.warn('xxx')、dog.error('xxx')
          if (node.type === 'CallExpression') {
            let isDogCall = false;

            // 匹配：dog('xxx')（直接调用）
            if (
              node.callee.type === 'Identifier' &&
              node.callee.name === 'dog'
            ) {
              isDogCall = true;
            }

            // 匹配：dog.warn('xxx')、dog.error('xxx')（成员调用）
            if (
              node.callee.type === 'MemberExpression' &&
              node.callee.object.type === 'Identifier' &&
              node.callee.object.name === 'dog' &&
              ['warn', 'error', 'info', 'type'].includes(
                node.callee.property.name,
              )
            ) {
              isDogCall = true;
            }

            // 标记需要移除的调用语句范围
            if (isDogCall) {
              removeRanges.add(`${node.start}-${node.end}`);
            }
          }

          /************************** 需求 3：移除 dun 相关导出和 if 代码块 **************************/
          // 3.1 匹配：export const dun = false
          if (
            node.type === 'ExportNamedDeclaration' &&
            node.declaration &&
            node.declaration.type === 'VariableDeclaration' &&
            node.declaration.kind === 'const'
          ) {
            node.declaration.declarations.forEach(declaration => {
              if (
                declaration.id.name === 'dun' &&
                declaration.init &&
                declaration.init.type === 'Literal' &&
                (declaration.init.value === false ||
                  declaration.init.value === true)
              ) {
                // 标记存在 dun = false，且移除该导出语句
                hasDunFalse = true;
                removeRanges.add(`${node.start}-${node.end}`);
              }
            });
          }

          // 3.2 匹配：if (dun) { ... }（仅当 hasDunFalse 为 true 时移除）
          if (hasDunFalse && node.type === 'IfStatement') {
            const testNode = node.test;
            if (testNode.type === 'Identifier' && testNode.name === 'dun') {
              // 移除整个 if 语句块
              removeRanges.add(`${node.start}-${node.end}`);
            }
          }
        },
      });

      // 5. 执行代码移除（处理所有标记的移除范围）
      Array.from(removeRanges).forEach(range => {
        const [start, end] = range.split('-').map(Number);
        magicStr.remove(start, end);
      });

      // 6. 返回修改后的代码和 sourcemap
      return {
        code: magicStr.toString(),
        map: magicStr.generateMap({ hires: true }), // 生成高精度 sourcemap
      };
    },
  };
}

module.exports = prodCodeTransformPlugin;

3. 插件使用方式​

在 Rollup 配置文件（rollup.config.js）中引入并使用该插件：

const prodCodeTransform = require('./prodCodeTransformPlugin');
const { terser } = require('rollup-plugin-terser'); // 可选，production 环境压缩代码

module.exports = {
  input: 'src/index.js', // 你的入口文件
  output: {
    file: 'dist/bundle.js',
    format: 'es', // 输出 ES 模块
  },
  plugins: [
    // 引入自定义插件，放在其他转换插件之后（比如 ts 插件）
    prodCodeTransform(),
    // 可选：production 环境压缩代码（建议添加）
    process.env.NODE_ENV === 'production' && terser(),
  ],
};

一、声明命令​

与普通命令一致，需要先在 contributes.commands 中进行注册：

{
  "contributes": {
    "commands": [
      // ... 其他命令
      {
        "command": "extensionName.submenuCommand1",
        "title": "插件的第一个子命令"
      },
      {
        "command": "extensionName.submenuCommand2",
        "title": "插件的第二个子命令"
      },
      {
        "command": "extensionName.submenuCommand3",
        "title": "插件的第三个子命令"
      },
      {
        "command": "extensionName.submenuCommand4",
        "title": "插件的第四个子命令"
      },
      {
        "command": "extensionName.submenuCommand5",
        "title": "插件的第五个子命令"
      },
      {
        "command": "extensionName.submenuCommand6",
        "title": "插件的第六个子命令"
      }
    ]
  }
}

二、构建菜单组​

自定义组需要显式的在 contributes.submenus 中定义子菜单命令组

{
  "contributes": {
    "submenus": [
      {
        "id": "extensionName.submenuCommandGroup0", // 唯一 id
        "label": "自定义菜单项 0"
      },
      {
        "id": "extensionName.submenuCommandGroup1",
        "label": "自定义菜单项 1"
      }
    ]
  }
}

三、将菜单子命令挂载到组​

子命令需要在（自定义）组中进行显示声明挂载才可显示在分组中：

{
  "contributes": {
    "menus": {
      "extensionName.submenuCommandGroup0": [
        {
          "command": "extensionName.submenuCommand1"
          // 这里可以配置该子项的显示规则
        },
        {
          "command": "extensionName.submenuCommand2"
        },
        {
          "command": "extensionName.submenuCommand2"
        }
      ],
      "extensionName.submenuCommandGroup1": [
        {
          "command": "extensionName.submenuCommand3"
        },
        {
          "command": "extensionName.submenuCommand4"
        },
        {
          "command": "extensionName.submenuCommand5"
        },
        {
          "command": "extensionName.submenuCommand6"
        }
      ]
    }
  }
}

四、将组挂载到菜单栏​

菜单项可以分组，按辞典序排列。可以将分组添加到菜单项，或中间、上方或上方添加新的菜单项组。

编辑器的右菜单项默认有以下分组：

• navigation - 群体在所有情况下都优先
• 1_modification - 修改代码命令组
• 9_cutcopypaste - 倒数第二组默认组，包含基本编辑命令
• z_commands - 最后一个默认组，带有打开命令调色板的条目

 ---------------------------
  Go to Definition
  Peek Definition                       ←--------       navigation
  Find All References
 ---------------------------
  Change All Occurrences
                                        ←--------       1_modification
  Format Document
 ---------------------------
  Cut
  Copy                                  ←--------       9_cutcopypaste
  Paste
 ---------------------------
  Command Palette ...                    ←--------       z_commands
 ---------------------------

可以将组放在任何想放置的位置

{
  "contributes": {
    "menus": {
      "editor/context": [
        {
          "submenu": "extensionName.submenuCommandGroup0",
          "group": "navigation@3", // 将 submenuCommandGroup0 自定义组放到了优先组
          "when": "true" // 控制该分组出现的条件
        },
        {
          "submenu": "extensionName.submenuCommandGroup1",
          "group": "9_cutcopypaste@5" // 将 submenuCommandGroup1 自定义分组放置到了剪辑命令组
        }
      ]
    }
  }
}

五、超级计划之​

1. 子命令匿于命令面板​

每一个没有特殊设置的 contributes.commands 子项都将可在命令面板 contributes.menus.commandPalette 可见, 而自分组的子项命令由于其特殊性，其 title 值可能将与其他专门用于控制面板的命令不同：

{
  "contributes": {
    "commands": [
      {
        "command": "extensionName.commandForCommandPalette0",
        "title": "extensionName: 专门用于控制面板的命令 0" // 为了显著，可能添加插件名
      },
      {
        "command": "extensionName.commandForCommandPalette1",
        "title": "extensionName: 专门用于控制面板的命令 1"
      },
      {
        "command": "extensionName.submenuCommand1",
        "title": "插件的第一个子命令" // 子组件由于分组的 label 已经有相关说明，可能更简洁
      },
      {
        "command": "extensionName.submenuCommand2",
        "title": "插件的第二个子命令"
      }
    ]
  }
}

如果不在 contributes.menus.commandPalette 中显式关闭分组，分组在命令面板可见。但又由于其 title 描述的不完整性，可能对用于不太友好：

{
  "contributes": {
    "menus": {
      "commandPalette": [
        {
          "command": "extensionName.submenuCommand1",
          "when": "false" // 关闭该命令在命令面板的显示
        },
        {
          "command": "extensionName.submenuCommand2",
          "when": "false"
        }
      ]
    }
  }
}

2. 多语言支持​

既然可能国际友人使用的情况比较少，但是功能不能不知晓。vsCode 提供原生支持！

使用 packages.nls.xxx.json 构建相应语言的示条，使用 packages.nls.json 设定默认（没有设定对应的语言时的兜底语言）。

{
  "name": "extensionName",
  "displayName": "%plugin.displayName%",
  "description": "%plugin.descriptions%",
  "contributes": {
    "commands": [
      {
        "command": "extensionName.command1",
        "title": "%command.command1%"
      },
      {
        "command": "extensionName.command2",
        "title": "%command.command2%"
      }
    ],
    "submenus": [
      {
        "id": "extensionName.submenus1",
        "label": "%submenus.submenus1%"
      },
      {
        "id": "extensionName.submenus2",
        "label": "%submenus.submenus2%"
      }
    ]
  }
}

{
  "plugin.displayName": "extension plugin display name in extensions store",
  "plugin.descriptions": "some text for describing extension plugin in extensions store",
  "command.command1": "extensionName: command1 description",
  "command.command2": "extensionName: command1 description",
  "submenus.submenus1": "extensionName: submenus1 description",
  "submenus.submenus2": "extensionName: submenus2 description"
}

{
  "plugin.displayName": "插件在扩展商城的展示名称",
  "plugin.descriptions": "插件在扩展商城展示的描述",
  "command.command1": "中文扩展名：命令 1 的描述",
  "command.command2": "中文扩展名：命令 2 的描述",
  "submenus.submenus1": "中文扩展名：子组 1 的描述",
  "submenus.submenus2": "中文扩展名：子组 2 的描述"
}

六、完整示意​

{
  "name": "super-file-header", // 扩展唯一 ID 名
  "publisher": "Mr.MudBean", // 发布者
  "displayName": "%plugin.displayName%", // 扩展在扩展商店展示名
  "description": "%plugin.description%", // 扩展在扩展商店展示描述
  "type": "commonjs", // 开发模式
  "version": "0.0.1", // 版本信息
  "license": "MIT", // 开源声明类型
  "engines": {
    "vscode": "^1.90.0" // 扩展支持的最低引擎
  },
  "categories": [
    "Other" // 功能分类
  ],
  "keywords": ["文件头注释"],
  "activationEvents": [
    // 启动事件
    "onLanguages:javascript",
    "onLanguages:javascriptreact",
    "onLanguages:typescript",
    "onLanguages:typescriptreact",
    "onLanguages:markdown",
    "onLanguages:mdx",
    "onLanguages:vue",
    "onStartupFinished"
  ],
  "main": "./dist/extension.js", // 扩展入口
  "contributes": {
    "commands": [
      {
        "command": "superFileHeader.createJavaScriptHeaderCommentPalette",
        "title": "%command.createJavaScriptHeaderComment%"
      },
      {
        "command": "superFileHeader.createJavaScriptHeaderCommentSubmenu",
        "title": "%submenu.createJavaScriptHeaderComment%"
      },
      {
        "command": "superFileHeader.createMdxPageHeaderCommentPalette",
        "title": "%command.createMdxPageHeaderComment%"
      },
      {
        "command": "superFileHeader.createMdxPageHeaderCommentSubmenu",
        "title": "%command.createMdxHeaderComment%"
      },
      {
        "command": "superFileHeader.createMdxBlogHeaderCommentPalette",
        "title": "%command.createMdxBlogHeaderComment%"
      },
      {
        "command": "superFileHeader.createMdxBlogHeaderCommentSubmenu",
        "title": "%command.createMdxBlogHeaderComment%"
      }
    ],
    "submenus": [
      {
        "id": "superFileHeader.createFileHeader",
        "label": "%submenus.createFileHeader%"
      }
    ],
    "menus": {
      "superFileHeader.createFileHeader": [
        {
          "command": "superFileHeader.createJavaScriptHeaderCommentSubmenu"
        },
        {
          "command": "superFileHeader.createMdxPageHeaderCommentSubmenu"
        },
        {
          "command": "superFileHeader.createMdxBlogHeaderCommentSubmenu"
        }
      ],
      "editor/context": [
        {
          "submenu": "superFileHeader.createFileHeader",
          "group": "1_modification@8"
        }
      ],
      "commandPalette": [
        {
          "command": "superFileHeader.createJavaScriptHeaderCommentPalette",
          "when": "resourceFilename =~ /\\.(js|ts|vue|jsx|tsx)$/"
        },
        {
          "command": "superFileHeader.createJavaScriptHeaderCommentSubmenu",
          "when": "false" // 显式关闭子命令在命令面板的显示
        },
        {
          "command": "superFileHeader.createMdxPageHeaderCommentPalette",
          "when": "resourceFilename =~ /\\.(md|mdx)$/"
        },
        {
          "command": "superFileHeader.createMdxPageHeaderCommentSubmenu",
          "when": "false" // 显式关闭子命令在命令面板的显示
        },
        {
          "command": "superFileHeader.createMdxBlogHeaderCommentPalette",
          "when": "resourceFilename =~ /\\.(md|mdx)$/"
        },
        {
          "command": "superFileHeader.createMdxBlogHeaderCommentSubmenu",
          "when": "false" // 显式关闭子命令在命令面板的显示
        }
      ]
    }
  }
  // ... 其他配置
}

其他辅助/规范开发的工具。（鉴于自己造破轮的经验，还是记录一下的好，省的以后在电器时代发现了磨石起火还自以为是）

一、提交细心规范​

确保团队提交信息清晰可追溯，配合 husky 可实现提交前校验。

• Commitlint ：校验 Git 提交信息格式（如是否符合 Conventional Commits 规范），用于 团队统一提交风格（如 feat: add login）
• Commitizen ： 交互式命令行引导生成标准化提交信息（替代手动输入 git commit -m ），用于 新手友好，避免格式错误
• cz-conventional-changelog ： Commitizen 适配器，生成符合 Conventional Commits 的提交信息，用于 配合 Commitizen 使用
• standard-version ： 自动根据提交信息生成 CHANGELOG.md、版本号和 Git 标签（SemVer），用于 发布流程自动化（替代手动改版本）

commitlint 就是用来强制约束 git commit 的信息格式，配套的 @commitlint/config-conventional 是业界通用的「Angular 规范」，要求 commit 信息必须是：类型(作用域): 描述 的格式 ：

# 不符合规范的 commit 信息被 commit 时，会直接拒绝提交，强制规范
git commit -m "feat(home): 新增首页轮播图组件"
git commit -m "fix(api): 修复用户列表接口数据返回异常的问题"
git commit -m "docs(readme): 更新项目部署文档"

二、CSS/样式规范​

针对 CSS/SCSS/Less 等样式文件的规范与格式化，与 Prettier 分工协作（Prettier 管格式，StyleLint 管规则）。

• Stylelint ： 校验 CSS/SCSS/Less 语法错误、规则一致性（如禁止使用 !important ），用于 样式代码质量控制
• stylelint-config-standard ： Stylelint 标准规则集（基于社区最佳实践），用于 快速上手，开箱即用
• postcss ： CSS 后处理器（配合 autoprefixer 自动加浏览器前缀、cssnano 压缩），用于 跨浏览器样式兼容、生产环境优化
• autoprefixer ： 根据 Can I Use 数据自动添加 CSS 浏览器前缀（如 -webkit- ），用于 替代手动写前缀，减少兼容性问题

三、代码生成与模板（减少重复劳动）​

自动生成重复代码（组件、页面、配置文件等），提升开发速度。

• Plop ： 轻量级代码生成工具（通过 Handlebars 模板定义生成规则），用于 生成 React 组件、Redux 模板等
• Hygen ： 高性能代码生成器（支持动态模板、多文件生成），用于 复杂项目模板（如 Monorepo 子包结构）
• Yeoman ： 老牌脚手架工具（生态丰富，可集成自定义生成器），用于 项目初始化、框架级模板生成
• create-react-app ： React 官方脚手架（内置 Webpack、Babel 配置），用于 快速创建 React 项目（现推荐 Vite）
• Vite ： 新一代前端构建工具（快速冷启动、热更新，内置模板生成），用于 替代 CRA，快速创建 TS/React/Vue 项目

四、依赖管理与优化​

自动化依赖更新、无用依赖检测、版本冲突解决。

• npm-check-updates (ncu) ： 扫描 package.json 并提示可更新的依赖版本（支持批量更新），用于 定期更新依赖，保持安全性
• depcheck ： 检测项目中未使用的依赖（ dependencies/devDependencies ） ，用于 清理冗余依赖，减小包体积
• patch-package ： 修改 node_modules 中依赖的源码并持久化补丁（无需 fork 仓库），用于 修复第三方依赖 bug（临时方案）
• npm-dedupe ：优化 node_modules 依赖树，合并重复依赖 ，用于 减小安装体积，提升加载速度

五、测试辅助（提升测试效率与质量）​

增强测试框架功能，规范测试用例，生成测试覆盖率报告。

• Jest ：全功能测试框架（单元测试、快照测试、Mock 函数），用于 React/Vue/Node.js 项目测试
• Vitest ：基于 Vite 的测试框架（更快速度、兼容 Jest API ），用于 Vite 项目首选，替代 Jest
• Testing Library ：组件测试工具（优先通过 DOM 语义查询元素，而非 test-id ），用于 React/Vue 组件行为测试
• eslint-plugin-jest ： ESLint 插件，校验 Jest 测试代码规范（如用例命名、断言风格 ），用于 测试代码质量控制
• nyc/istanbul ：生成测试覆盖率报告（标记未覆盖代码），用于 CI 流程中强制覆盖率阈值

六、文档自动化（减少手动维护成本）​

自动生成 API 文档、组件文档、README 等。

• Storybook ：组件开发环境（可视化展示组件、编写交互用例、生成文档），用于 React/Vue/Angular 组件文档
• Typedoc ：基于 TypeScript 类型生成 API 文档（支持 Markdown 注释提取），用于 TS 项目 API 文档自动化
• JSDoc ：通过注释生成文档（需配合 eslint-plugin-jsdoc 规范注释），用于 JS 项目基础文档生成
• docsify ：轻量级文档网站生成器（基于 Markdown ，无需构建），用于 项目 README 扩展为在线文档
• Sphinx ：Python 生态文档工具（支持多语言，常用于开源项目），用于 大型项目多语言文档

七、环境变量与配置管理​

统一管理开发/测试/生产环境变量，避免硬编码。

• dotenv ： 从 .env 文件加载环境变量到 process.env，用于 本地开发环境配置
• cross-env ： 跨平台设置环境变量（解决 Windows 下 NODE_ENV=production 语法问题），用于 统一 CI/CD 与本地环境变量设
• dotenv-cli ： 命令行加载 .env 文件（如 dotenv -e .env.prod node app.js ），用于 多环境切换执行命令
• conf ： 轻量级 Node.js 配置管理（支持 JSON/YAML/JS 文件，自动合并层级配置），用于 应用配置集中管理

八、Git 增强与协作​

除 husky 和 lint-staged 外，提升 Git 协作效率的工具。

• Git LFS ： 大文件存储（将二进制文件如图片、视频存储在 Git 外，仅保留指针），用于 游戏、设计资源管理
• diff-so-fancy ： 美化 Git 差异输出（高亮变更、简化 diff 格式），用于 提升代码 review 效率
• gh (GitHub CLI) ： 命令行操作 GitHub （创建 PR 、管理 Issue、查看仓库），用于 替代网页端操作，提升协作速度

九、构建与打包辅助​

优化构建流程、分析包体积、加速编译。

• webpack-bundle-analyzer ：可视化分析 Webpack 打包产物体积（识别大依赖），用于 优化包体积，减少首屏加载时间
• source-map-explorer ：分析 Source Map 定位代码体积瓶颈（支持 Webpack/Vite/Rollup ），用于 精准优化代码拆分
• concurrently ：并行运行多个命令（如 npm run dev:server & npm run dev:client ），用于 多进程开发（前后端联调）
• rimraf ：跨平台删除文件/文件夹（替代 rm -rf ，Windows 兼容），用于 构建前清理 dist 目录

十、编辑器与 IDE 辅助（VS Code 插件）​

虽非 npm 插件，但能显著提升编码效率（需手动安装 VS Code 插件）。

• ES7+ React Snippets ：提供 React/Vue 代码片段（如 rfc 生成函数组件），用于 快速生成组件模板
• Path Intellisense ：自动补全文件路径（导入组件/资源时），用于 避免手写路径错误
• Error Lens ：在代码行内直接显示 ESLint/TypeScript 错误（无需看 Problems 面板），用于 实时错误反馈
• GitLens ：增强 Git 功能（显示代码作者、提交历史、分支对比），用于 代码溯源与协作

十一、Monorepo 管理（多包仓库协作）​

针对 Lerna/Yarn Workspaces/Turborepo 的辅助工具。

• Turborepo ：高性能 Monorepo 构建系统（缓存任务结果、并行执行、依赖图优化），用于 大型 Monorepo 加速构建与测试
• Lerna ：老牌 Monorepo 管理工具（版本管理、包发布、依赖链接），用于 中小型 Monorepo 包管理
• Changesets ：管理 Monorepo 包版本与变更日志（配合 Turborepo 使用），用于 多包协同发布，自动生成 CHANGELOG

十二、其他实用工具​

解决特定痛点的轻量工具。

• EditorConfig ：统一不同编辑器的缩进、换行符等基础格式（需项目根目录 .editorconfig ），用于 跨编辑器协作格式一致
• nodemon ：监听文件变化自动重启 Node.js 服务（开发环境），用于 后端 API 开发热重载
• serve ：快速启动静态文件服务器（支持 HTTPS 、Gzip ），用于 本地预览打包后的 dist 目录
• http-server ：轻量级 HTTP 服务器（比 serve 更简单），用于 临时分享静态文件

之前比较忽略 eslint 插件的使用，现在发现还不错。是我肤浅了。

• 按需安装 ： 避免堆砌插件，根据项目类型和痛点选择（例如：React 项目必装 eslint-plugin-react+ eslint-plugin-react-hooks）
• 组合配置 ：多数插件提供预设配置（如 eslint-plugin-react/configs/recommended），直接继承减少手动配置
• 版本兼容 ：注意插件与 ESLint 版本的兼容性（参考插件文档的 peerDependencies）

一、常用插件​

• @eslint/js 适用于 js 的通用配置
  eslint.config.mjs 片段

  import js from '@eslint/js'; // 必须：核心推荐规则
  export default [
    // 基础配置（所有文件通用）
    js.configs.recommended, // 必须：ESLint 核心推荐规则
    // ... 其他规则
  ];
  

• eslint-plugin-jsdoc JSDoc 对 ESLint 的 linting 规则
  eslint.config.mjs 片段

  import jsdocPlugin from 'eslint-plugin-jsdoc'; // 可选：JSDoc 注释
  export default [
    // ... 其他规则
    // 5.1 可选：JSDoc 注释规范
    {
      files: ['**/*.{js,ts,jsx,tsx}'],
      plugins: { jsdoc: jsdocPlugin },
      rules: {
        // 基础规则
        'jsdoc/check-alignment': 'error',
        'jsdoc/check-param-names': 'error',
        'jsdoc/check-tag-names': [
          'error',
          {
            // 配置允许的标签
            definedTags: ['packageDocumentation'],
          },
        ],
        'jsdoc/check-types': 'error',
        // TypeScript 适配规则
        'jsdoc/no-types': 'error',
        'jsdoc/require-param-type': 'off', // 使用 TS 类型
        'jsdoc/require-returns-type': 'off', // 使用 TS 类型
        // 文档质量规则
        'jsdoc/require-description': [
          'error',
          {
            contexts: ['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'],
          },
        ],
        'jsdoc/require-jsdoc': [
          'warn',
          {
            require: {
              FunctionDeclaration: true,
              MethodDefinition: true,
              ClassDeclaration: true,
            },
          },
        ],
      },
    },
    // ... 其他规则
  ];
  

• eslint-config-prettier 关闭所有不必要的规则或可能与 Prettier 冲突的规则
  eslint.config.mjs 片段

  import prettierConfig from 'eslint-config-prettier'; // 必须：关闭 Prettier 冲突规则
  export default [
    // ... 其他规则
    // 关闭 Prettier 冲突规则（必须，用 Prettier 时）
    prettierConfig, // 必须放在最后
  ];
  

• typescript-eslint 工具可以让你在 ESLint 上使用 TypeScript
  eslint.config.mjs 片段

  import tseslint from 'typescript-eslint'; // 必须：TypeScript 支持
  export default [
    // ... 其他规则
    // TypeScript 配置（必须）
    ...tseslint.configs.recommended.map(config => ({
      ...config,
      files: ['src/**/*.{ts,tsx}'],
      languageOptions: {
        ...config.languageOptions,
        globals: {
          ...globals.browser,
          ...globals.node,
          ...globals.es2025, // 浏览器 + Node +  ES2025 全局
        },
        parserOptions: {
          ...config.languageOptions?.parserOptions,
          tsconfigRootDir: import.meta.dirname, // ESM 获取当前配置目录
          project: true, // 类型感知规则，或者指定实际的 tsconfig.json
          ecmaVersion: 'latest',
          sourceType: 'module',
          ecmaFeatures: { jsx: true }, // 开启JSX解析，适配React
        },
      },
      rules: {
        // TS 核心规则（示例）
        '@typescript-eslint/no-explicit-any': 'error',
        '@typescript-eslint/no-unused-vars': [
          'error',
          { argsIgnorePattern: '^_' },
        ],
        '@typescript-eslint/prefer-nullish-coalescing': 'error',
      },
    })),
    // ... 其他规则
  ];
  

• react 用：
  • eslint-plugin-react React 核心规则（组件规范、Props 校验、 jSX 最佳实践），用于 React 含 JSX 项目
  • eslint-plugin-react-hooks React Hooks 规则（如 useState/useEffect 依赖数组校验），用于使用 Hooks 的 React 的项目
• next.js 用
  • eslint-plugin-next Next.js专用规则（路由、SSR、Image 组件优化），用于 Next.js 全栈项目
• angular 用
  • eslint-plugin-angular Angular 规则（组件、服务、 RxJS 最佳实践），用于 AngularJS/Angular 项目
• vue 用
  • eslint-plugin-vue Vue 单文件组件（ SFC ）规则（模版语法、 Composition API 、 选项式 API ）
• Nuxt 用
  • eslint-plugin-nuxt Nuxt 专用规则（页面/组件结构、中间件、 SEO ）