如何实现JSDoc的@example标签引入外部文件示例代码，替代手动复制？

我太懂你这种手动同步示例代码的烦躁了——每次改完示例还要复制粘贴到JSDoc里，不仅麻烦还容易出错！下面给你两个实用的方案，不用搞复杂的模板引擎就能解决问题：

方案一：用JSDoc专用插件实现自动引入 #

有不少JSDoc插件专门支持从外部文件加载@example内容，完全不用手动复制。你可以直接npm安装这类插件，然后在代码里这样写：

// index.js
/**
 * @example {@link ./index.example.js}
 */
function add(a, b) {
  return a + b;
}

不同插件的语法可能略有差异，有些支持更简洁的@example ./index.example.js，它们会在生成JSDoc文档时自动把外部示例文件的内容嵌入到@example标签对应的位置，最终效果和你手动把代码写进去完全一样。而且你编辑index.example.js时，编辑器的语法高亮、错误提示和类型安全功能都能正常用，完美满足你的需求。

方案二：轻量级自定义脚本同步 #

如果不想依赖第三方插件，写个几行的Node.js小脚本也能搞定，完全算不上“过度工程”。比如创建一个sync-example.js文件：

const fs = require('fs');
const path = require('path');

// 读取外部示例文件内容
const exampleCode = fs.readFileSync(path.join(__dirname, 'index.example.js'), 'utf8');
// 读取目标JS文件内容
const targetFileContent = fs.readFileSync(path.join(__dirname, 'index.js'), 'utf8');

// 替换JSDoc里的示例占位符
const updatedContent = targetFileContent.replace(
  /\/\*\*\s*\* @example import\("index.example.js\)\s*\*\//,
  `/**
   * @example
   * ${exampleCode.split('\n').map(line => ` * ${line}`).join('\n')}
   */`
);

// 将更新后的内容写回文件
fs.writeFileSync(path.join(__dirname, 'index.js'), updatedContent);

然后在你的package.json里加一个脚本命令：

{
  "scripts": {
    "sync-example": "node sync-example.js"
  }
}

每次改完index.example.js，只需要在终端跑一下npm run sync-example，脚本就会自动把最新的示例代码同步到JSDoc里，比手动复制高效多了。

这两种方案都能帮你摆脱手动复制的麻烦，而且完全符合你想要的“等价于手动写入示例”的效果。

备注：内容来源于stack exchange，提问作者Eliav Louski