部署Gatsby站点到AWS Amplify报错无法解析@parcel/namer-default模块

DevOps 小满

2026-8-27

修复方案

这个报错的核心原因是构建环节@gatsbyjs/parcel-namer-relative-to-cwd无法加载其依赖的@parcel/namer-default包，属于依赖安装异常，和Node版本无直接关系，按以下步骤排查修复：

本地先验证依赖完整性
删除本地项目的node_modules目录、对应包管理器的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装后跑gatsby build，如果本地复现同样报错，直接手动安装缺失的依赖：
npm用户执行：
```
npm install @parcel/namer-default --save-dev
```
yarn用户执行：
```
yarn add @parcel/namer-default --dev
```
安装完成后本地构建验证通过，将更新后的package.json和锁文件提交到代码仓库。

清理Amplify构建缓存
绝大多数这类部署报错都和Amplify的历史依赖缓存损坏有关，进入Amplify控制台对应项目的构建设置页，选择「清除缓存后重新部署」触发一次构建。如果仍失败，修改项目根目录的amplify.yml构建配置，固定依赖安装逻辑，避免安装阶段丢包：

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # npm用户保留下面这行，注释yarn的命令
        - npm ci
        # yarn用户保留下面这行，注释npm的命令
        # yarn install --frozen-lockfile
    build:
      commands:
        - gatsby build
  artifacts:
    baseDirectory: public
    files:
      - "**/*"
  cache:
    paths:
      - node_modules/**/*
      - public/**/*
      - .cache/**/*

修复Gatsby版本兼容问题
部分Gatsby 4.x早期版本存在parcel相关依赖的声明错误，会导致包管理器无法自动拉取传递依赖，直接将Gatsby升级到最新稳定版即可：
```
npm install gatsby@latest --save
```
升级后本地验证构建正常，再提交代码触发部署。
兜底配置
以上操作都无效的话，在项目根目录新建.npmrc文件，写入以下配置放宽依赖安装校验规则，强制拉取所有层级的依赖：
```
legacy-peer-deps=true
strict-peer-deps=false
```
提交该文件后重新触发构建即可。