Obsidian 插件市场打不开、插件装不上怎么办

「插件装不上」是 Obsidian 新手最容易卡住的一步，而且它其实是四个完全不同的问题，表现相似、原因和解法却毫不相干。先对号入座，再往下看对应那一节：

你看到的现象	真正的问题	去看
点「浏览」后一直转圈 / 空白 / 提示加载失败	连不上插件市场	第二节
市场能打开，但搜不到某个插件	那个插件不在市场里	第三节
装完了，「已安装插件」列表里没有	文件放错层级 / 需要刷新	第四节
列表里有，但开关打不开 / 打开又弹回去	安全模式或插件本身报错	第五节

一、先做一件事：确认安全模式已关闭

不管哪种情况，先确认这一步——第一次使用第三方插件时，Obsidian 默认是不允许加载任何插件的。

打开 设置 → 第三方插件，如果看到一个安全模式的提示页，点最下方的 「关闭安全模式」：

没关这一项，后面所有安装动作看起来都会「成功」，但插件就是不生效。这是「插件装了没反应」最常见的原因，没有之一。

关掉之后，「社区插件市场」旁边才会出现可点的 「浏览」 按钮：

二、市场打不开：一直转圈、加载不出来

点了「浏览」之后一直转圈、列表空白、或者提示加载失败——这几乎都是网络问题，不是你的 Obsidian 坏了。

原因很直接：社区插件的列表和插件文件本身都托管在境外，国内网络环境下时通时不通。同一台电脑，可能上午能打开、下午就一直转圈。

能试的几件事，按顺序：

1. 等一会儿再试。这种不通往往是间歇性的，隔十几分钟重开一次设置页经常就好了。
2. 换个网络。手机热点、家里宽带、公司网络的出口不一样，换一个常常立刻就通。
3. 重启 Obsidian。市场列表有缓存，卡在半截的状态重启后会重新拉取。

如果上面都不行，别在市场这条路上耗着——直接跳到第六节，有两条不依赖插件市场的安装路径。

顺带说一个常被误判的情况：市场能打开、插件详情页也能进，但点「安装」之后卡在下载。这同样是网络问题——列表和插件文件是分开托管的，列表能拉到不代表文件下得动。处理方式一样。

三、市场能打开，但搜不到想装的插件

先排除两种常见的搜索问题：

• 搜索框认的是插件的「显示名」，不一定是你听说的那个名字。 很多插件的中文名和市场里登记的英文名不一样，搜中文搜不到、搜英文就出来了，反之亦然。
• 拼写和空格。市场搜索比较死板，多一个空格、少一个字母都可能搜不出来。

排除完还是搜不到，那答案通常很朴素：这个插件根本不在插件市场里。

Obsidian 的社区插件市场有一套审核流程，不是所有插件都会走这条路——有的作者选择只发安装包、有的还在审核中、有的因为各种原因短期内不上架。插件不在市场里，不代表它不能用，只是需要换一种装法（见第六节）。

📢 「手机电脑同步」就属于这种情况：本插件短期内不会上架 Obsidian 插件市场，在市场里直接搜是搜不到的。请按下面第六节的方式安装——装出来的插件功能完全一致，而且照样会自动更新。

四、装完了，列表里却没有

如果你是手动放文件的方式安装（下载 zip、解压、拷进插件目录），装完在「已安装插件」里找不到，99% 是文件夹层级不对。

正确的结构必须是这样，plugins/<插件名>/ 下面直接就是那几个文件：

你的笔记库/
└── .obsidian/
    └── plugins/
        └── shoujidiannao/
            ├── main.js
            ├── manifest.json
            └── styles.css

两种典型的错法：

• 多套了一层：plugins/shoujidiannao/shoujidiannao/main.js —— 解压工具自动建了同名文件夹，你又建了一个。
• 少套了一层：plugins/main.js —— 解压出来是散开的三个文件，直接拖进了 plugins 目录。

有的解压工具会自动把文件收进一个同名文件夹，有的直接把三个文件解出来。解压后先看一眼是文件夹还是散文件，再决定要不要自己建这一层。

找不到 .obsidian 目录？ 它是隐藏文件夹，不用去系统里翻。让 Obsidian 直接帮你打开：设置 → 第三方插件 →「已安装插件」那一行右边，点文件夹图标：

放好文件之后，回到「已安装插件」那一行点刷新图标，或者干脆重启一次 Obsidian——新拷进去的插件不刷新是不会自己出现的，很多人卡在这里以为装失败了。

五、列表里有，但启用不了

列表里能看到插件、但开关打不开，或者打开之后又自动弹回关闭：

1. 先回第一节确认安全模式真的关了。 安全模式下开关会被强制拨回去。
2. 看看插件版本要求。 有的插件要求较新的 Obsidian 版本，版本太旧会加载失败。到「设置 → 关于」看一眼当前版本，需要的话升级 Obsidian。
3. 重启 Obsidian 再试一次。 插件是在启动时加载的，中途放进去的文件偶尔需要重启才能正确初始化。
4. 确认三个文件都在。只拷了 main.js 少了 manifest.json，Obsidian 认不出这是个插件；manifest.json 损坏或不完整也会导致同样的结果。

六、不经过插件市场安装插件的两条路

路线 A：用「快速安装插件」（推荐）

插件市场里有一个叫 China BRAT 的小工具，作用就是从一个地址直接把插件装进来，不经过插件市场的搜索和分发。它本身在市场里，**搜「快速安装插件」**就能找到：

点进去装好、启用：

然后进它的设置页。不用在输入框里填任何地址——下面的「示例」里已经列好了几个插件，找到「手机电脑同步」这一行，点右边的 「填入并安装」：

几秒钟后提示「已安装 手机电脑同步 vX.X.X」，左侧列表里就有了，而且已经自动启用：

这条路的好处：安装来源是国内可直连的地址，不受访问境外站点不顺畅的影响；装好之后插件会自己检查更新，不用手动升级。

手机上步骤完全一样，逐步截图见《手机用快速安装插件装插件》。

路线 B：下载安装包手动装

插件市场彻底打不开、连 China BRAT 都装不了的时候用这条：

1. 从官网下载打包好的插件 zip；
2. 解压出 main.js、manifest.json、styles.css 三个文件；
3. 按第四节的结构放进 .obsidian/plugins/shoujidiannao/；
4. 回到「第三方插件」刷新或重启，打开开关。

完整图文见《介绍与安装使用入门》· 备选：下载安装包手动安装。

七、手机上有什么不一样

手机端（iOS / Android / 鸿蒙）的逻辑和电脑完全一致，只有两处操作路径不同：

• 进设置的方式：点左上角图标展开侧边栏，再点右下角的齿轮图标。

  

• 手动放文件更麻烦：手机上要用文件管理器进到笔记库的 .obsidian/plugins/ 里建文件夹、拷文件，隐藏目录还常常看不见。所以手机上强烈建议走路线 A（「快速安装插件」），全程在 Obsidian 里点几下就完成，不碰文件管理器。

手机端完整图文：《手机用快速安装插件装插件》｜《手机用 BRAT 安装插件》

八、常见问题

Q：插件市场打不开，会影响已经装好的插件吗？ 不会。插件装好之后就在你本地了，运行完全不需要插件市场。市场只在「安装」和「检查更新」时才用到。

Q：「快速安装插件」和 BRAT 是一个东西吗？ 思路一样，都是「从地址装插件」。区别是：快速安装插件（China BRAT）不用填地址，点内置示例即可，安装来源在国内直连更稳；BRAT 需要填仓库地址、经过境外站点。两种方式装的是同一个插件，后装的会覆盖先装的，不会重复。

Q：装完之后还要留着 China BRAT 吗？ 建议留着。以后想装预览版抢先体验新功能时还会用到它。不想要也可以随时卸载，不影响已装好的插件。

Q：我有好几个笔记库，能把配置好的插件文件夹复制过去吗？ 千万不要。 那个文件夹里存着「这个库对应哪个云端库」的绑定信息，复制过去会让几个本地库被认成同一个云端库，导致文件互相覆盖污染。正确做法是在新库里干净地装一遍、单独初始化。

Q：装好之后怎么开始用？ 点设置左侧「第三方插件」分组里的「手机电脑同步」进入设置页，点「获取登录验证码」，用微信把 6 位数字发给「笔记同步助手」公众号即可。完整流程见《介绍与安装使用入门》。