便携版Python执行pip命令提示‘module pip not found’问题排查

我写了一个Node.js脚本，用来检查指定版本的Python是否已安装，未安装则通过压缩包安装便携版。Python本身可正常执行，但运行.\python.exe -m pip install xyz命令时，系统提示pip未安装；然而在Python安装目录的Scripts和lib文件夹中，明明能看到pip.exe程序。相关脚本及调用代码如下：

Node.js脚本代码 #

import { exec, spawn } from 'child_process';
import fs from 'fs';
import axios from 'axios';
import os from 'os';
import path from 'path';

const platform = os.platform();

async function getPythonPath(version: string): Promise<string> {
    const pythonFolder = path.join("public", "python", version)
    const pythonCmd = path.join(pythonFolder, 'python');

    if (fs.existsSync(pythonFolder)) {
        return platform === "win32" ? pythonCmd + ".exe" : pythonCmd;
    }

    let pythonUrl: string,
        pythonZipPath: string,
        unzipCmd: string,
        pipCmd: string;
    if (platform === 'win32') {
        pythonUrl = `https://www.python.org/ftp/python/${version}/python-${version}-embed-amd64.zip`;
        pythonZipPath = path.join(os.tmpdir(), `python-${version}.zip`);
        unzipCmd = `7z x ${pythonZipPath} -o${pythonFolder}`;
        pipCmd = `${pythonCmd}.exe ${path.join(pythonFolder, 'get-pip.py')}`;
    } else if (platform === 'darwin') {
        pythonUrl = `https://www.python.org/ftp/python/${version}/python-${version}-macosx10.9.pkg`;
        pythonZipPath = path.join(os.tmpdir(), `python-${version}.pkg`);
        unzipCmd = `sudo installer -pkg ${pythonZipPath} -target /`;
        pipCmd = `sudo ${pythonCmd} ${path.join(pythonFolder, 'get-pip.py')}`;
    } else {
        throw new Error('Unsupported platform');
    }

    try {
        console.log(`Downloading Python ${version}...`);
        const response = await axios({
            method: 'get',
            url: pythonUrl,
            responseType: 'stream',
        });

        const fileStream = fs.createWriteStream(pythonZipPath);
        response.data.pipe(fileStream);

        await new Promise<void>((resolve, reject) => {
            fileStream.on('finish', resolve);
            fileStream.on('error', reject);
        });

        await new Promise<void>((resolve, reject) => {
            console.log(`Unzipping Python ${version}...`);
            exec(unzipCmd, (error) => {
                if (error) {
                    reject(error);
                } else {
                    resolve();
                }
            });
        });

        // Download get-pip.py
        console.log('Downloading get-pip.py...');
        const getPipUrl = 'https://bootstrap.pypa.io/get-pip.py';
        const getPipScriptPath = path.join(pythonFolder, 'get-pip.py');
        const getPipResponse = await axios({
            method: 'get',
            url: getPipUrl,
        });

        fs.writeFileSync(getPipScriptPath, getPipResponse.data);

        await new Promise<void>((resolve, reject) => {
            console.log('Installing pip...');
            exec(pipCmd, (error) => {
                if (error) {
                    reject(error);
                } else {
                    resolve();
                }
            });
        });

        return platform === "win32" ? pythonCmd + ".exe" : pythonCmd;
    } catch (error) {
        throw error;
    }
}

export async function pyrun(scriptPath: string, pythonVersion: string, callback: (text: string) => void, onerror: (text: string) => void): Promise<void> {
    return new Promise<void>(async (resolve, reject) => {

        const pythonExecutable = await getPythonPath(pythonVersion);
        const command = `${pythonExecutable} ${scriptPath}`;

        exec(command, (error, stdout, stderr) => {
            if (error) {
                reject(error);
            } else {
                resolve();
            }

            if (stdout && callback) {
                callback(stdout);
            }

            if (stderr && onerror) {
                onerror(stderr);
            }
        });
    });
}

调用代码 #

import path from "path";
import { pyrun } from "../basic-py-run";

async function main() {
    const version = '3.9.0';
    const installScript = path.join('public', 'python', version) + ' -m pip install cowsay';

    await pyrun(installScript, version, (text) => {
        console.log(text)
    }, (error) => {
        console.error(error);
    });

}

main();

问题原因与修复方案 #

1. 核心原因：嵌入式Python的配置限制 #

你下载的是Python嵌入式包（python-${version}-embed-amd64.zip），这类包默认启用环境隔离，不会自动识别site-packages目录（pip模块的安装位置），即使手动安装了pip，Python也无法找到对应的模块。

2. 具体修复步骤 #

（1）修改Python配置文件

在Python安装目录下找到python${version}._pth文件（例如python39._pth），打开后添加以下两行内容：

Lib\site-packages
.

这会让Python识别site-packages目录，从而找到pip模块。

（2）修正调用代码逻辑

你的调用代码存在参数传递错误：pyrun函数会自动拼接Python可执行路径，不需要把Python路径作为参数传入。修改后的调用代码如下：

async function main() {
    const version = '3.9.0';
    // 直接传递pip命令参数即可
    const installArgs = '-m pip install cowsay';

    await pyrun(installArgs, version, (text) => {
        console.log(text)
    }, (error) => {
        console.error(error);
    });
}

（3）确保pip安装到正确路径

安装pip时，需要指定安装目录为Python的site-packages，避免安装到系统全局路径。修改getPythonPath函数中的pipCmd定义：

// 先确保site-packages目录存在
const sitePackagesDir = path.join(pythonFolder, 'Lib', 'site-packages');
if (!fs.existsSync(sitePackagesDir)) {
    fs.mkdirSync(sitePackagesDir, { recursive: true });
}
// 修改pip安装命令
pipCmd = `${pythonCmd}.exe ${path.join(pythonFolder, 'get-pip.py')} --target ${sitePackagesDir}`;

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