如何让Markdown文件间的链接同时在本地和Bitbucket生效？

核心问题 #

本地VSCode预览时，根相对路径（如/abc/components/card/readme.md）能正常跳转，但Bitbucket会把根斜杠解析为Bitbucket域名根目录，导致404；硬编码Bitbucket绝对URL则本地会跳转到在线页面，无法访问本地文件。

可行解决方案 #

1. 使用基于当前文件的相对路径（推荐）

Bitbucket支持相对于当前Markdown文件的相对路径，同时VSCode预览也能正确识别这类路径。
你的componentReadmes.md位于/docs/目录下，组件README在仓库根目录的/abc/components/下，只需要把链接改成向上跳出docs目录的相对路径：

* [Card](../abc/components/card/readme.md)
* [Image Block](../abc/components/image-block/readme.md)
* [Tabs](../abc/component/tabs/readme.md)

• 本地VSCode预览：会从docs目录向上一级，再定位到abc/components下的文件，正常跳转；
• Bitbucket打开：会自动把相对路径解析为仓库根目录起始的路径，生成https://bitbucket.org/projects/XYZ/repos/xyz-components/browse/abc/components/card/readme.md这类正确链接。

2. 用脚本/Git钩子自动转换（备选）

如果不想手动修改路径，可以写简单脚本配合Git钩子：

• 本地开发时保留根相对路径；
• 提交代码前，用pre-commit钩子将根相对路径替换为Bitbucket兼容的格式（或直接替换为方案1的相对路径）；
• 也可以生成两个版本的文件，一个供本地使用，一个提交到仓库，但这种方式需要额外维护，不推荐。

3. 配置Bitbucket路径别名（团队场景）

如果是团队协作，可联系Bitbucket管理员为仓库配置路径别名，将/abc/映射到正确的仓库路径。但此方法需要管理员权限，仅适用于团队统一配置的场景。

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