Vue 3 应用在 x86_64 开发机上跑得好好的，换到 ARM 服务器、树莓派或 Apple Silicon 的 Linux 虚拟机里，却经常在 npm install 阶段就报错。翻日志会发现真正卡住的是 esbuild、@rollup/rollup-linux-arm64-gnu 这类平台相关二进制包没有被正确安装。这个问题的本质不是 Vue 自身的语法或运行时，而是前端工程化链条里的原生依赖与 CPU 架构绑定过紧。Vite 作为 Vue 3 的默认构建工具，强依赖 esbuild 做依赖预构建和压缩，同时 Rollup 在生产构建阶段也会加载平台特定的原生模块。只要有一个包在 arm64 上缺失，整个构建流程就会中断。
要解决这类问题，不能只靠换 Node 版本或者简单重装依赖。工程化的目标应当是让同一份 package.json 和锁文件能够在 x86_64 与 AArch64 两个平台上稳定展开，并且 CI 产物能够自动覆盖 arm64 镜像或部署包。下面从架构影响、依赖处理、多平台构建和缓存调优几个角度展开。
先厘清：AArch64 对 Vue 3 工程化的实际影响
AArch64 是 ARM 64 位架构的官方名称，常见于云服务器的 Graviton 系列、树莓派 4B/5、Apple Silicon 以及部分国产化终端。Vue 3 本身的运行时是用 JavaScript 写的，理论上与 CPU 架构无关，但 Vite 工具链并不是纯 JavaScript。Vite 在开发模式下使用 esbuild 做依赖预构建，而 esbuild 是一个用 Go 编写的原生二进制，通过 npm 的可选依赖机制按平台下载。也就是说，在 arm64 Linux 上安装 esbuild 时，npm 应当拉取 @esbuild/linux-arm64 这个包；如果锁文件里只记录了 x64 的二进制，或者 npm 的架构探测失败，就会回退到错误的包甚至直接跳过可选依赖。
同样的问题也出现在 Rollup 4.x 上。Rollup 从 3 开始拆分了大量平台相关包，例如 @rollup/rollup-linux-arm64-gnu 与 @rollup/rollup-linux-arm64-musl。如果项目在 x86_64 机器上生成 package-lock.json 后直接复制到 ARM 机器，npm ci 会严格按照锁文件中的 resolved 地址和平台字段安装，轻则跳过原生包导致运行时找不到共享库，重则安装 x64 版本的二进制然后报 Exec format error。理解这一点后，工程化改造的重点就很清楚：让依赖解析过程显式感知 CPU 与 libc。
还有一个容易被忽略的影响是内存与文件系统。ARM 单板设备的内存通常远小于 x86 服务器，Vite 开发服务器的依赖预构建和 HMR 文件监听会占用更多资源。如果把 node_modules 放在 SD 卡或网络文件系统上，大量小文件读写会进一步拖慢启动速度。因此 AArch64 环境下的工程化不仅要做架构兼容，还要针对低配设备调整缓存目录和构建参数。
依赖与工具链的架构兼容处理
最直接的方案是重新生成锁文件。在 ARM 机器上删除 node_modules 与 package-lock.json，再执行一次干净的 npm install，让 npm 根据当前平台解析出正确的可选依赖。但这样会破坏锁文件的跨平台一致性，团队里如果同时存在 x64 开发机和 arm64 服务器，就必须维护两份锁文件，这显然不是理想的工程化状态。npm 从 7 开始支持在锁文件中记录多个平台的依赖信息，只要 CI 或本地环境满足一定条件，一份 package-lock.json 可以同时覆盖 linux-x64、linux-arm64 和 darwin-arm64。
要想生成包含多平台信息的锁文件，建议在一台 x86_64 开发机上执行以下命令，强制声明需要解析的架构与 libc 组合：
npm install --package-lock-only \ --cpu=arm64 --os=linux --libc=glibc \ --cpu=x64 --os=linux --libc=glibc
这里用到了 npm 的 --cpu、--os 与 --libc 参数。它们会覆盖当前平台探测结果，让 npm 在解析依赖时同时考虑 arm64 与 x64 的可选包。执行完成后，package-lock.json 中 packages 节点下的 esbuild 与 rollup 相关条目会出现多个平台变体，并且每个条目带有 cpu、os 和 libc 字段。之后在 arm64 机器上执行 npm ci，npm 会根据本机平台选择对应的二进制包，不会再出现架构错配。
如果团队使用 pnpm，处理方式略有不同。pnpm 默认只解析当前平台的依赖，但可以通过 .npmrc 中的 supportedArchitectures 字段显式开启多平台解析。例如：
supportedArchitectures[]=linux-arm64-gnu supportedArchitectures[]=linux-x64-gnu
这段配置放在仓库根目录的 .npmrc 中即可。pnpm 在生成 pnpm-lock.yaml 时会额外记录这些平台的原生依赖，后续在 CI 或 ARM 设备上安装时就不会出现 optional dependency 缺失。需要注意的是，supportedArchitectures 从 pnpm 8 开始表现稳定，旧版本可能需要通过 --config.platform 或 --config.arch 临时指定。
对于 Yarn 用户，Yarn 2+ 的 supportedArchitectures 配置也类似，可以写在 .yarnrc.yml 中，列出 os、cpu 与 libc 组合。无论使用哪种包管理器，核心原则都是把平台信息写进依赖解析配置，而不是依赖某个机器的临时探测结果。
多架构构建与 CI 实践
如果最终产物是静态文件，Vue 3 构建完成后其实与架构无关，真正需要 arm64 环境的是构建过程本身。因此很多团队选择在 CI 中直接使用 arm64 runner 或通过 Docker buildx 进行跨平台构建。前者最省事但 arm64 runner 资源相对较少，后者利用 QEMU 模拟可以在 x86_64 主机上跑 arm64 容器，适合构建镜像并同时发布多架构版本。
以 Docker buildx 为例，先确认本机已经启用 binfmt_misc 与 QEMU 支持。Docker Desktop 通常内置，Linux 主机可以执行 docker run --rm --privileged tonistiigi/binfmt --install all 来注册模拟器。然后创建一个多架构 builder：
docker buildx create --name multi-arch --use docker buildx inspect --bootstrap
Dockerfile 的写法不需要做太多特殊处理，但要注意基础镜像的选择。Node 官方镜像已经提供了 linux/arm64 版本，直接使用 node:20-alpine 即可。构建阶段先安装依赖并产出 dist，运行阶段用 nginx 托管静态文件。一个简洁的多阶段构建示例如下：
FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci && npm run build FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html EXPOSE 80
上面代码中的 && 在 HTML 源码中已经做了转义，实际渲染后会显示为 bash 中的逻辑与运算符。生产环境如果使用非 root 用户或需要自定义 nginx 配置，可以继续追加配置。关键命令是构建与推送时同时指定 --platform：
docker buildx build \ --platform linux/amd64,linux/arm64 \ -t your-registry/vue3-app:latest \ --push .
这样一次构建就能产出 amd64 与 arm64 两个镜像。在 Kubernetes 集群中，如果同时存在 x86 与传统 ARM 节点，调度器会根据节点架构自动选择对应镜像。对于云上的 Graviton 实例，直接使用 arm64 镜像也能获得更好的成本收益。需要注意的是，QEMU 模拟构建的速度会明显慢于原生构建，如果项目依赖大量原生模块或构建时间很长，建议同时配置一个原生 arm64 runner 作为辅助，或者使用支持 arm64 的云端 CI 服务。
如果不需要镜像，只想要一个能在 ARM 机器上直接运行的 dist 目录，可以在 CI 中增加 arm64 job，运行 npm ci 与 npm run build，然后将 dist 打包成 tar.gz 或 zip 上传到制品库。这种情况下，前文提到的多平台锁文件就是先决条件，否则 arm64 job 会在依赖安装阶段失败。
Vite 在 ARM 平台上的性能与缓存调优
AArch64 设备并不总是性能羸弱，云上的 Graviton3 单核性能已经相当可观，但很多团队是在树莓派、工控机或开发板上运行 Vue 3 开发服务器。这类设备内存有限，SD 卡随机读写慢，而 Vite 的依赖预构建会扫描并重写大量 CommonJS 模块，默认把缓存放在 node_modules/.vite 目录下。如果 node_modules 位于网络文件系统或低性能存储上，首次启动会非常慢。
一个简单的优化是把 Vite 缓存目录迁移到内存文件系统或本地 SSD。可以通过 cacheDir 配置实现：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
cacheDir: '/tmp/vite-cache'
})
这里把缓存放到 /tmp 后，重启后缓存会丢失，但 tmpfs 的读写速度远高于 SD 卡。更稳妥的做法是在设备初始化时创建 /var/cache/vite 并挂载 tmpfs，或者使用外接 USB3 SSD 存放项目与 node_modules。另一个优化点是减少预构建范围。Vite 默认会预构建所有 bare import 的依赖，但某些大型 UI 库并不需要被重写，可以通过 optimizeDeps.exclude 跳过：
export default defineConfig({
optimizeDeps: {
exclude: ['some-large-cjs-lib']
}
})
但这需要确认该库本身提供 ESM 版本，否则浏览器会直接报错。对于依赖数量较少的项目，开启 build.sourcemap 的 false 值也能减少 ARM 设备上的内存占用。生产构建方面，可以设置 build.assetsInlineLimit 与 build.chunkSizeWarningLimit 来减少小文件数量，降低部署时的 IO 压力。
此外，如果同时使用 Vitest 跑单元测试，它的默认并发数可能超过低配 ARM 设备的承受范围。可以通过命令行参数 --pool=forks 或配置文件中的 test.pool 控制并发，避免测试阶段因为内存不足被系统 OOM Killer 终止。工程化不只是让构建能跑起来，还要让整个开发、测试、发布链路在目标架构上稳定执行。
AArch64 生态正在快速成熟，Vue 3 与 Vite 对 ARM 64 位的支持已经相当完善。只要在项目初期做好锁文件架构声明、在 CI 中明确多平台构建策略、在低配设备上针对缓存与并发做调优，同一套 Vue 3 代码就能从 x86_64 平滑交付到 ARM 64 位环境。遇到原生依赖报错时，先检查 npm config get cpu 与锁文件中的平台字段，通常比盲目重装更有用。