在以 macOS 为主的团队里，前端构建产物的归档往往依赖网盘、U 盘或者手动拷贝，时间一长版本混乱、找不到历史包的情况时有发生。其实 macOS 生态自带一套成熟的文件共享方案，就是 AFP（Apple Filing Protocol，苹果归档协议）。把它接入 Vue 3 的工程化流程，可以让每次 npm run build 之后自动把 dist 目录推送到归档服务器，实现可追溯的版本管理。本文就来完整梳理这套方案的落地过程。
AFP 协议是什么，它在前端工程化中扮演什么角色
AFP 全称 Apple Filing Protocol，中文常译作苹果归档协议或苹果文件协议，是苹果为 Macintosh 系统设计的网络文件共享协议。它深度集成于 macOS 的访达，支持资源分支、用户权限、Spotlight 搜索等特性，早期是 Mac 之间共享文件的首选方式。虽然在 macOS 高版本中苹果逐步转向 SMB 协议，但大量存量归档服务器、NAS 设备仍然以 AFP 作为主要对外协议，因为它对老款 Mac 客户端兼容性更好，权限模型也更贴合苹果的习惯。
把它放到前端工程化的语境里，AFP 的价值在于提供了一块网络挂载的存储空间。Vue 3 项目通过 Vite 构建出 dist 目录后，需要有一个稳定的地方存放这些静态资源，无论是供测试环境直接访问，还是作为历史版本归档备查。AFP 服务器恰好能承担这个角色：客户端挂载 AFP 共享目录后，它就像本地磁盘一样可读写，构建脚本可以用普通的文件操作 API 完成上传，不需要额外的 FTP 客户端或者对象存储 SDK。
和常见的替代方案对比一下会更清晰。SMB 协议跨平台性最好，Windows、Linux、Mac 都能访问，但在纯苹果环境中权限语义有偏差；NFS 性能高但配置复杂，且不适合跨公网；而对象存储（如各类云 OSS）虽然可靠，但需要额外引入 SDK 和密钥管理。如果团队本身已经有一台 macOS 机器作为文件服务器，AFP 几乎是零成本的选择，开箱即用。
服务端准备：在 macOS 上开启 AFP 共享并规划目录结构
第一步是在归档服务器上启用文件共享。打开系统设置中的通用、共享选项，勾选文件共享，然后在共享文件夹中添加一个专门用于前端归档的目录，比如 /SharedArchives/frontend。接着点击该共享目录的信息按钮，在选项中启用 AFP 方式共享，并为部署用的账号分配读写权限。需要注意的是，从 macOS 某些版本开始 AFP 选项可能默认隐藏，如果找不到开关，可以通过服务器管理工具或者命令行确认 afpd 服务状态。
目录结构建议按项目、分支、版本号三层组织，例如 /SharedArchives/frontend/my-vue-app/main/1.4.2/，同一层级再放一个 latest 软链接指向最新版本。这样测试人员可以直接通过 latest 路径访问最新构建，需要回溯历史时也能按版本号快速定位。这种结构配合后面脚本中的时间戳命名，可以做到每一次构建都有据可查。
安全方面有两点要提醒。一是尽量为部署账号创建专用系统账户，不要用管理员账号做自动化传输；二是如果归档服务器暴露在办公网之外，建议通过 VPN 或者 SSH 隧道转发 AFP 端口，AFP 协议本身的历史漏洞不少，公网直连的风险不可忽视。
客户端接入：Node 环境下访问 AFP 共享的两种方式
在构建机上访问 AFP 共享，实践中有两条路线。第一条是系统级挂载：构建脚本执行前，先用命令行把共享目录挂载到本地路径，之后的文件操作完全等同于本地磁盘。以 macOS 构建机为例，核心命令如下：
# 挂载 AFP 共享目录到本地 mkdir -p /mnt/frontend-archive mount_afp afp://deploy:password@192.168.1.10/frontend /mnt/frontend-archive # 卸载（部署完成后清理） umount /mnt/frontend-archive
这种方式的优点是对 Node 脚本零侵入，挂载完成后用 fs-extra 就能拷贝文件，代码简单直观。缺点是需要处理密码传递问题，明文写在脚本里不安全，建议改用钥匙串中的凭据，或者在 CI 环境中通过环境变量注入并配合 expect 工具交互输入。
第二条路线是使用 Node 原生 AFP 客户端库，比如社区维护的 node-afp，直接在代码里建立连接、列出目录、写入文件，省去系统挂载步骤。示例代码：
import { createAfpClient } from 'node-afp';
import fse from 'fs-extra';
import path from 'node:path';
const client = await createAfpClient({
host: '192.168.1.10',
user: process.env.AFP_USER,
password: process.env.AFP_PASS,
volume: 'frontend'
});
// 目标版本目录，例如 my-vue-app/main/1.4.2
const version = process.env.APP_VERSION || 'dev-' + Date.now();
const target = path.posix.join('my-vue-app', 'main', version);
// 递归上传 dist 目录到归档服务器
async function uploadDir(localDir, remoteDir) {
const files = await fse.readdir(localDir, { withFileTypes: true });
for (const f of files) {
const localPath = path.join(localDir, f.name);
const remotePath = `${remoteDir}/${f.name}`;
if (f.isDirectory()) {
await client.mkdir(remotePath, { recursive: true });
await uploadDir(localPath, remotePath);
} else {
const buf = await fse.readFile(localPath);
await client.writeFile(remotePath, buf);
}
}
}
await client.mkdir(target, { recursive: true });
await uploadDir('dist', target);
console.log('归档完成:', target);
await client.close();两种方式怎么选？如果构建机本身就是 Mac，系统挂载更省事也更稳定；如果构建环境跑在 Linux 容器里，node-afp 这类纯协议实现的依赖更少，但要留意库的活跃度和对不同 AFP 版本的兼容性，建议先在小文件量场景下验证传输稳定性。
整合到 Vue 3 工程：Vite 构建钩子与 CI 流水线串联
方案确定后，把它接入 Vue 3 项目的日常流程。先在 vite.config.js 中约定构建输出目录，保持默认的 dist 即可，重点是定义环境变量文件，把服务器地址、账号、版本号等配置统一收口到 .env.deploy 中，避免硬编码。然后在 package.json 的 scripts 中新增一条归档命令：
{
"scripts": {
"build": "vite build",
"deploy:archive": "vite build && node scripts/archive-to-afp.mjs"
}
}归档脚本 archive-to-afp.mjs 就是上一节上传逻辑的封装，这里补充一个实用细节：上传前先做一次清单校验，读取 dist 下所有文件的字节数，上传完成后再从 AFP 端读取一次做比对，防止网络抖动导致产物残缺。归档成功后还可以在版本目录里写一个 meta.json，记录构建时间、Git 提交哈希、Node 版本等信息，后续排查线上问题时能快速对应到具体代码版本。
如果团队使用 CI 流水线，整个流程可以进一步自动化。流水线的典型阶段是：拉取代码、安装依赖、执行构建与归档、最后发送通知。归档阶段通过环境变量注入 AFP 凭据，脚本拿到 APP_VERSION 后自动创建版本目录。再配合一个定时清理任务，定期删除 N 个版本之前的旧目录，控制归档空间的占用。跑通之后，开发者本地只需要提交代码，构建产物就会源源不断地沉淀到 AFP 服务器上，测试同学直接访问版本目录或 latest 路径即可验收，整个链路不再依赖任何人工拷贝。
最后提一个容易踩的坑：AFP 传输大量小文件时效率不如 SMB，Vue 项目 dist 里动辄几百个 js、css 分包文件，首次全量上传可能偏慢。可以在上传前先用 gzip 打成单个压缩包归档，归档目录里同时保留压缩包和解压后的目录，既兼顾速度，又方便直接访问。这套方案整体投入不大，却能明显改善前端产物的管理秩序，值得在苹果环境为主的团队中尝试。