Laravel Sail执行sail up报错npm: not found 求解决方法

核心原因 #

Laravel Sail默认的PHP镜像未预装Node.js/npm，若构建过程中触发了npm命令（比如前端依赖安装），就会出现该错误；另外Windows下项目位置、WSL2配置不当也可能引发此类问题。

修复步骤 #

1. 确认项目存储位置 #

Windows环境下必须将Laravel项目放在WSL2的Linux文件系统内（例如\\wsl$\Ubuntu\home\你的用户名\projects），禁止放在Windows本地盘符（如C:\），否则会导致文件权限、镜像构建异常。

2. 在PHP镜像中预装Node.js/npm #

修改Sail的PHP运行时Dockerfile，手动添加npm安装步骤：

• 进入项目根目录下的vendor/laravel/sail/runtimes/[你的PHP版本]目录（比如8.2）
• 打开Dockerfile，在apt-get安装依赖的区块后添加以下代码：

# 安装Node.js 20.x和npm
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    npm install -g npm@latest

• 保存后执行以下命令重新构建镜像：

sail build --no-cache
sail up

3. 单独用Node容器处理前端依赖（推荐） #

无需修改PHP镜像，在docker-compose.yml中新增Node服务，分离前端构建流程：

services:
    # 保留原有laravel.test等服务配置
    node:
        image: node:20-alpine
        working_dir: /var/www/html
        volumes:
            - '.:/var/www/html'
        command: npm install && npm run dev
        networks:
            - sail

执行以下命令启动Node服务安装依赖：

sail up -d node

之后再启动主服务即可：

sail up -d

4. 检查WSL2与Docker集成配置 #

• 打开Docker Desktop，进入设置 > 资源 > WSL集成，确保你正在使用的WSL发行版（如Ubuntu）已启用
• 重启Docker Desktop和WSL终端，确保配置生效

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