Hugo站点搭建避免 icloud 云盘同步

这是一份为你整理的**“Hugo 项目 iCloud 防同步终极指南”**。你可以把这份指南当作“备忘录”，以后在 Mac 上新建任何前端或 Hugo 项目放在 iCloud 里时，都可以直接套用这套方案。

这套方案的核心逻辑是：

iCloud 默认不会同步任何以 .nosync 结尾的文件或文件夹。 对于可以指定输出路径的文件夹（如 public），直接通过命令参数重定向到 .nosync 文件夹。 对于工具强制写死路径的文件夹（如 node_modules 和 resources），使用“实体放入 .nosync 文件夹 + 原地创建软链接”的“偷梁换柱”法骗过工具。 以下是完整的操作步骤梳理：

第一步：在终端中建立软链接（防同步 node_modules 和 resources）

在新项目的根目录下打开终端，执行以下命令，将那些产生海量碎片文件的目录全部转移并建立快捷方式：

# 1. 处理 node_modules（依赖库，文件数量极多）
# 如果项目刚 clone 下来还没安装依赖，用 mkdir；如果已经有了，用 mv 移动
rm -rf node_modules.nosync
mv node_modules node_modules.nosync 2>/dev/null || mkdir node_modules.nosync
ln -s node_modules.nosync node_modules

# 2. 处理 resources（Hugo 图片/资源缓存）
rm -rf resources.nosync
mv resources resources.nosync 2>/dev/null || mkdir resources.nosync
ln -s resources.nosync resources

⚠️ 避坑指南（非常重要）：做这一步时，绝对不要使用 pnpm 安装依赖！pnpm 的底层机制会在 node_modules 产生上万个软链接，iCloud 依然会卡死。请务必使用原生的 npm 或 yarn。

第二步：修改 package.json（防同步 public）

Hugo 编译生成的静态网站默认放在 public 文件夹中。我们通过修改本地的运行脚本，给 Hugo 加上 -d public.nosync 参数，让它直接把网站生成到防同步文件夹里。

在 package.json 的 scripts 中做类似如下修改：

  "scripts": {
    "dev": "hugo server -d public.nosync",
    "build": "hugo --minify -d public.nosync",
    "pagefind": "pagefind --site public.nosync" 
  }

(注意：这里主要改本地脚本，云端部署的脚本配置保持默认的 public 即可，云端不受 iCloud 影响。)

第三步：修改 Hugo 配置文件（防止本地热更新卡死）

因为我们创建了几个庞大的 .nosync 文件夹，当你在本地运行 hugo server 时，Hugo 的文件监听器（Watcher）会去扫描它们，导致启动极慢或报错。 需要在 Hugo 的配置文件（如 hugo.yaml 或 config.toml）中，将这些文件夹加入忽略列表：

ignoreFiles:
  - "node_modules\\.nosync"
  - "resources\\.nosync"
  - "public\\.nosync"

第四步：修改 .gitignore（防止被推送到 GitHub）

既然我们在本地生成了 .nosync 的真实文件夹，就不能让 Git 把它们识别为代码变更。在项目根目录的 .gitignore 文件末尾加上：

# iCloud no-sync folders
public.nosync/
resources.nosync/
node_modules.nosync/

💡 总结与云端部署提醒

完成以上 4 步后，你的本地项目就能在 iCloud 中拥有极致的丝滑体验，再也不会让 Mac 风扇狂转、云盘卡在“正在同步 15,000 个文件”了。

关于云端部署（GitHub Actions 或 Netlify）： 云端环境没有 iCloud 烦恼，所以我们在云端保持完全常规的配置：

让云端执行普通的 npm install。 让云端执行普通的 hugo –minify（默认输出到 public）。 部署目标文件夹填写默认的 public。 这样一套“内外有别”的架构，既照顾了本地 Mac 的开发体验，又保证了云端持续集成的标准与稳定！