刘炳琦1. 为什么需要在Mac上手动安装PicGo Gitee插件
在Mac环境下使用PicGo搭配Gitee图床时，很多用户会发现官方插件市场里找不到Gitee上传插件。这不是你的错觉——由于Gitee平台政策调整，PicGo官方应用商店确实下架了该插件。但通过手动安装方式，我们依然可以完美解决这个问题。
我最近在自己的M1芯片MacBook Pro上就遇到了这个需求。作为一名长期使用Markdown写作的技术博主，图床工具是刚需。Gitee作为国内稳定的代码托管平台，其仓库功能很适合作为私人图床使用。经过多次尝试和踩坑，我总结出了这套可靠的安装方案。
手动安装的核心原理是：PicGo作为基于Electron的应用程序，其插件系统本质上是通过Node.js的npm包机制实现的。即使官方市场不可用，我们仍然可以通过直接安装插件npm包的方式扩展功能。这种方式在开发者圈子被称为"侧载安装"。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与前置检查
2.1 Node.js环境确认
首先打开终端，运行以下命令检查Node.js是否已安装：
bash复制node -v
npm -v
如果看到版本号输出（建议Node.js 14+，npm 6+），说明环境已就绪。如果没有安装，可以通过以下两种方式之一安装：
- 官方pkg安装包：
bash复制# 下载LTS版本
curl -O https://nodejs.org/dist/v18.16.0/node-v18.16.0.pkg
sudo installer -pkg node-v18.16.0.pkg -target /
- 通过Homebrew安装：
bash复制brew install node
注意：在M系列芯片的Mac上，建议使用Rosetta模式运行终端安装，避免架构兼容性问题。可以通过"终端-右键-获取信息-使用Rosetta打开"来设置。
2.2 PicGo基础安装
如果你还没有安装PicGo主程序，推荐通过Homebrew cask安装：
bash复制brew install --cask picgo
或者从GitHub下载最新dmg安装包：
bash复制curl -LO https://github.com/Molunerfinn/PicGo/releases/download/v2.3.1/PicGo-2.3.1.dmg
hdiutil attach PicGo-2.3.1.dmg
cp -R /Volumes/PicGo/PicGo.app /Applications
安装完成后，先启动一次PicGo完成初始化。建议在Dock中保留图标，方便后续操作。
3. 手动安装Gitee插件全流程
3.1 定位PicGo插件目录
关键步骤来了！我们需要找到PicGo存储插件的目录位置。在Mac上，路径通常为：
code复制~/Library/Application\ Support/picgo/node_modules/
可以通过以下命令快速进入：
bash复制cd ~/Library/Application\ Support/picgo/
mkdir -p node_modules # 确保目录存在
3.2 安装插件依赖
Gitee插件需要一些额外的依赖库。在插件目录下执行：
bash复制npm install picgo-plugin-gitee-uploader --save
npm install crypto-js mime-types -S
这里有个常见坑点：如果遇到权限错误，千万不要使用sudo！正确的做法是：
bash复制# 先修复目录权限
sudo chown -R $(whoami) ~/Library/Application\ Support/picgo
# 然后重新安装
npm install picgo-plugin-gitee-uploader --save
3.3 插件配置激活
安装完成后，重启PicGo应用。你应该能在"插件设置"中看到gitee-uploader选项。点击齿轮图标进入配置：
json复制{
"repo": "你的用户名/仓库名",
"branch": "master",
"token": "你的Gitee个人令牌",
"path": "img/",
"customUrl": "https://gitee.com/你的用户名/仓库名/raw/master"
}
获取token的方法：
- 登录Gitee → 设置 → 私人令牌
- 生成新令牌，勾选"projects"权限
- 复制令牌字符串（只会显示一次，务必保存好）
安全提示：token相当于你的账户密码，千万不要上传到公开仓库或分享给他人。如果不慎泄露，立即到Gitee重置令牌。
4. 常见问题排查指南
4.1 插件安装后不显示
如果按照上述步骤操作后，PicGo中仍然看不到插件，可能是以下原因：
-
目录位置错误：
- 检查是否在正确的
~/Library/Application Support/picgo/node_modules/目录安装 - 使用
npm list -g --depth=0查看全局安装位置
- 检查是否在正确的
-
版本冲突：
bash复制# 删除重试 rm -rf node_modules/picgo-plugin-gitee-uploader npm cache clean --force npm install picgo-plugin-gitee-uploader@1.2.0 --save # 指定稳定版本 -
PicGo未加载插件：
- 完全退出PicGo（Command+Q）
- 删除
~/Library/Application Support/picgo/data.json - 重新启动
4.2 上传失败错误处理
当遇到上传失败时，可以依次检查：
-
网络连通性：
bash复制
curl -I https://gitee.com ping gitee.com -
仓库配置检查：
- 确保仓库是公开的（私有仓库需要额外配置）
- 确认分支名称正确（新仓库默认可能是main而非master）
-
Token权限验证：
bash复制curl -H "Authorization: token 你的TOKEN" https://gitee.com/api/v5/user应该返回你的用户信息
-
图片大小限制：
- Gitee单文件限制1MB（未认证）或20MB（认证用户）
- 大文件建议先压缩或使用其他图床
4.3 M1芯片特有问题
苹果Silicon芯片可能会遇到以下问题：
-
Node.js架构问题：
bash复制# 查看当前架构 node -p "process.arch" # 如果是arm64，尝试x86模式 arch -x86_64 zsh -
Electron兼容性：
在终端用Rosetta模式启动PicGo：bash复制cd /Applications/PicGo.app/Contents/MacOS arch -x86_64 ./PicGo
5. 高阶配置与优化技巧
5.1 自定义域名加速
Gitee原生访问速度有时不稳定，可以通过CDN加速：
-
在插件配置中将customUrl改为：
json复制"customUrl": "https://cdn.jsdelivr.net/gh/你的用户名/仓库名@master" -
需要先在仓库创建
_config.yml文件：yaml复制jsDelivr: enabled: true
5.2 自动重命名与压缩
在PicGo设置中开启：
- "时间戳重命名"
- "上传前压缩图片"
或者添加自定义脚本：
javascript复制// 在~/.picgo/config.js中添加
module.exports = {
handle: async (ctx) => {
const { output } = await ctx.cmd.invoke('convert ${input} -quality 85 ${output}')
return output
}
}
5.3 多仓库负载均衡
创建多个Gitee小号，配置多个插件实例：
json复制{
"picgoPlugins": {
"gitee-uploader1": {
"repo": "账号1/仓库1",
"token": "token1"
},
"gitee-uploader2": {
"repo": "账号2/仓库2",
"token": "token2"
}
},
"uploader": "gitee-uploader1"
}
通过快捷键切换上传目标：
bash复制defaults write com.molunerfinn.picgo uploader gitee-uploader2
这套方案在我的M1 Mac上稳定运行了半年多，配合Typora实现Markdown图片自动上传，极大提升了写作效率。遇到问题欢迎在评论区交流，我会持续更新解决方案。