如何在TypeScript JSDoc中引用本地Markdown文件为可点击链接？

针对你遇到的WebStorm和VSCode中JSDoc本地相对路径链接无法跳转的问题，可以按以下方式处理：

VSCode 适配方案 #

1. 确保相对路径层级准确
   路径是相对于当前注释所在文件的位置，比如你的函数文件在src/utils/http.ts，而csrf-issues.md在项目根目录的docs文件夹下，那么正确的相对路径应该是../../docs/csrf-issues.md（每一层../对应向上回退一级目录）。
   调整后的JSDoc示例：

   /**
    * my function description... 
    * @see {@link ../../docs/csrf-issues.md} 
    * @param httpClientRef : AxiosInstance
    * @return {Promise<void>}
    */
   export const httpClientSetCsrfToken = async (httpClientRef) => {...}
   

2. 使用Markdown链接格式替代
   部分情况下，VSCode对Markdown原生的[链接文本](路径)格式支持更好，你可以这样写：

   /**
    * my function description... 
    * @see [CSRF问题说明文档](../../docs/csrf-issues.md)
    * @param httpClientRef : AxiosInstance
    * @return {Promise<void>}
    */
   

WebStorm 适配方案 #

1. 使用项目根路径变量
   WebStorm支持通过$PROJECT_DIR$变量直接指向项目根目录，无需计算相对层级，兼容性更稳定：

   /**
    * my function description... 
    * @see {@link $PROJECT_DIR$/docs/csrf-issues.md} 
    * @param httpClientRef : AxiosInstance
    * @return {Promise<void>}
    */
   

2. 验证路径大小写
   WebStorm在区分大小写的系统中对文件路径大小写敏感，确保JSDoc中的路径和实际文件的大小写完全一致。

跨IDE通用技巧 #

• 可以同时提供两种格式的链接，兼顾不同编辑器的支持：

  /**
   * my function description... 
   * @see {@link ../../docs/csrf-issues.md} | [CSRF问题文档](../../docs/csrf-issues.md)
   * @param httpClientRef : AxiosInstance
   * @return {Promise<void>}
   */
  

• 确保目标文件确实存在于指定路径下，避免因文件移动或重命名导致链接失效。

内容的提问来源于stack exchange，提问作者Chen Peleg