Docker构建Gridsome/Vue站点后出现gridsome: not found错误求助

核心原因分析 #

gridsome: not found通常由以下情况导致：

• Gridsome仅本地安装在node_modules中，但启动时直接调用全局命令gridsome，容器内未全局安装Gridsome
• yarn install未正确执行，依赖未完成安装
• 工作目录（WORKDIR）配置错误，导致node_modules路径异常，启动命令无法找到执行文件
• 容器PATH未包含本地node_modules/.bin目录，无法读取本地安装的Gridsome命令

具体修复方案 #

1. 修正Dockerfile配置 #

使用符合Node 16.x + yarn要求的Dockerfile，确保依赖安装和环境配置正确：

# 指定Node 16.x版本的基础镜像，内置yarn
FROM node:16.20.2-bullseye-slim

# 设置工作目录
WORKDIR /app

# 先复制依赖配置文件，利用Docker缓存
COPY package.json yarn.lock ./

# 锁定依赖版本安装，避免版本波动
RUN yarn install --frozen-lockfile

# 复制项目全部文件
COPY . .

# 将本地依赖的bin目录加入PATH，确保能调用本地安装的命令
ENV PATH="/app/node_modules/.bin:${PATH}"

# 启动Gridsome开发服务，指定0.0.0.0允许外部访问
CMD ["yarn", "run", "gridsome", "develop", "--host", "0.0.0.0"]

2. 调整docker-compose.yml配置 #

确保端口映射正确，同时避免本地卷覆盖容器内的node_modules：

version: '3.8'
services:
  gridsome-site:
    build: .
    ports:
      - "8080:8080"
    volumes:
      # 挂载本地项目文件，但排除node_modules
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development

3. 检查package.json依赖配置 #

确保Gridsome已添加到依赖列表，并且启动脚本正确：

{
  "name": "your-gridsome-site",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "develop": "gridsome develop",
    "build": "gridsome build",
    "explore": "gridsome explore"
  },
  "dependencies": {
    "gridsome": "^0.7.23",
    "@gridsome/source-filesystem": "^0.6.2"
  },
  "devDependencies": {
    // 你的其他开发依赖
  }
}

4. 重新构建并启动容器 #

执行以下命令彻底清理旧容器并重新构建：

docker-compose down -v
docker-compose build --no-cache
docker-compose up

关键注意事项 #

• 不要在容器内全局安装Gridsome，依赖项目本地安装即可，避免版本冲突
• 卷挂载必须排除node_modules，否则本地空目录会覆盖容器中已安装的依赖
• 启动命令必须用yarn run gridsome或./node_modules/.bin/gridsome，不能直接调用gridsome（除非全局安装）
• 严格使用Node 16.x版本，不要跨版本使用，避免兼容性问题

内容的提问来源于stack exchange，提问作者indigowalrus