如何一步步将自己的 PHP 包上传到 Packagist

本文旨在指导开发者如何从零开始，通过 Composer 创建、管理并发布自己的 PHP 包到 Packagist 平台，使其他人能够通过 composer require 命令轻松安装使用。我们将分四步详细介绍整个过程：

第一步：安装 Composer

1.1 下载并安装 Composer（适用于中国大陆用户）

由于网络原因，国内用户访问官方源可能较慢或失败，推荐使用 phpComposer 镜像站 提供的安装方式：

✅ 官方推荐命令（国内可用）：

scss 复制代码

bash
深色版本
php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

步骤说明：

下载安装器：

less 复制代码

bash
深色版本
php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"

执行安装脚本：

arduino 复制代码

bash
深色版本
php composer-setup.php

删除临时文件：

scss 复制代码

bash
深色版本
php -r "unlink('composer-setup.php');"

设置全局命令（Linux/macOS 用户）：

bash 复制代码

bash
深色版本
sudo mv composer.phar /usr/local/bin/composer

验证是否成功：

css 复制代码

bash
深色版本
composer --version

Windows 用户设置步骤：

将 composer.phar 放入 PHP 安装目录下（如 C:\xampp\php）。
创建 composer.bat 文件，内容如下：
css 复制代码
```
深色版本
@php "%~dp0composer.phar" %*
```
确保 PHP 已加入系统环境变量。

1.2 设置国内镜像加速（强烈推荐）

中国大陆用户建议设置 Composer 使用国内镜像以提升速度：

arduino 复制代码

bash
深色版本
composer config -g repo.packagist composer https://packagist.phpcomposer.com

或者手动编辑全局配置文件（位于 ~/.composer/config.json）添加：

json 复制代码

json
深色版本
{
    "repositories": {
        "packagist": {
            "type": "composer",
            "url": "https://packagist.phpcomposer.com"
        }
    }
}

第二步：新建自己的包

2.1 初始化一个新的 Composer 项目

在你的项目根目录下执行以下命令初始化一个新的 composer.json 文件：

csharp 复制代码

bash
深色版本
composer init

按照提示填写相关信息，例如包名、描述、作者等。你也可以手动创建 composer.json 文件。

2.2 `composer.json` 中常用的字段解释

以下是一个典型的 composer.json 示例及其字段解释：

python 复制代码

json
深色版本
{
    "name": "dzl/one",
    "description": "我的第一个库e",
    "type": "library",
    "require": {
        "monolog/monolog": "^2.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^9.5",
        "phpstan/phpstan": "^1.0"
    },
    "autoload": {
        "psr-4": {
            "One\": "src/"
        }
    },
    "scripts": {
        "test": "phpunit",
        "analyze": "phpstan analyse src tests"
    },
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "authors": [
        {
            "name": "dzl",
            "email": "[email protected]"
        }
    ],
    "license": "MIT",
    "repositories": [
        {
            "type": "vcs",
            "url": "https://gitee.com/dzl/one.git"
        }
    ]
}

字段详解：

字段	描述
`name`	格式为 `作者名/包名`，用于唯一标识你的包。
`description`	对项目的简要描述。
`type`	包类型，常见值有 `library`（库）、`project`（完整项目）等。
`require`	定义项目运行时所需的依赖包。
`require-dev`	定义开发环境所需的依赖包。
`autoload`	定义自动加载规则，通常使用 PSR-4 或 PSR-0 标准。
`scripts`	自定义脚本命令。
`config`	全局配置选项。
`minimum-stability` 和 `prefer-stable`	控制版本稳定性要求。
`authors`	定义作者信息。
`license`	定义使用的许可证类型。
`repositories`	自定义仓库地址。

💡 提示：更多关于 composer.json 的详细信息可以单独生成一篇文章深入探讨。

第三步：将包上传到 Gitee

3.1 在 Gitee 上新建仓库

登录 gitee.com
点击右上角"+" → "新建仓库"
输入仓库名称（如 my-project）
勾选"空仓库"，不要勾选"初始化 README"
点击"创建"

3.2 进入项目目录，初始化 Git

bash 复制代码

bash
深色版本
cd /path/to/your/project
git init

这将在当前目录下生成 .git 文件夹，表示该项目现在是一个 Git 仓库。

3.3 添加所有文件到暂存区

csharp 复制代码

bash
深色版本
git add .

将当前目录下的所有文件加入 Git 的版本控制队列中。

3.4 提交初始版本

sql 复制代码

bash
深色版本
git commit -m "init"

这是你的第一次提交，建议使用 "init" 或 "Initial commit" 这类统一格式。

3.5 关联远程仓库地址

复制你在 Gitee 创建仓库时提供的 HTTPS 地址，通常是：

arduino 复制代码

深色版本
https://gitee.com/你的用户名/仓库名.git

然后执行：

csharp 复制代码

bash
深色版本
git remote add origin https://gitee.com/你的用户名/仓库名.git

📌 示例：

csharp 复制代码

bash
深色版本
git remote add origin https://gitee.com/dzl/my-project.git

3.6 推送代码到远程仓库

perl 复制代码

bash
深色版本
git push -u origin master

首次推送时需加上 -u 参数，用于绑定默认分支。

如果你遇到主分支是 main 的情况，请使用：

css 复制代码

bash
深色版本
git push -u origin main

第四步：在 Packagist 上绑定 Gitee 包的路径

4.1 注册 Packagist 账号

访问 packagist.org
点击右上角 "Sign up"
输入用户名、邮箱、密码，完成注册

💡 推荐绑定 GitHub 账号，方便后续同步更新。

4.2 提交你的 Git 仓库地址

登录 packagist.org
点击右上角用户名 → "Submit"
在输入框中填写你的 Git 仓库地址（Gitee 或 GitHub 的 .git 地址）
- 示例：
  perl 复制代码
```
深色版本
https://gitee.com/dzl/my-project.git
```
点击 "Check & Submit"

📌 注意：

仓库必须包含有效的 composer.json 文件；
若你是第一次提交，Packagist 会开始抓取你的仓库信息；
如果一切正常，你会看到包正在被索引。

4.3 审核通过后，如何引入自己的包

一旦审核通过，你的包就会出现在 Packagist 主页上，其他人就可以通过以下命令安装你的包：

bash 复制代码

bash
深色版本
composer require dzl/one

💡 提示：

以后每次提交新版本 tag 到 Git，Packagist 会自动检测并更新包版本；
可以使用 GitHub Webhook 自动触发更新（见 Packagist 页面提示）。

五、常见问题及解决方法

❗ 报错示例：

vbnet 复制代码

bash
深色版本
remote: [session-7347cbab] reject by mode [i]
fatal: unable to access 'https://gitee.com/gexinyuming/study.git/': The requested URL returned error: 400

🔍 原因分析：

这个错误通常由以下几种情况引起：

可能原因	解决办法
Gitee 初始化了 README 文件	删除本地 `.git` 文件夹，重新执行 `git init`、`git add .`、`git commit` 和 `git remote add origin <url>`，最后再推送
网络不稳定或代理设置问题	更换网络环境（如切换 WiFi 或有线连接）、关闭 Git 的代理设置：`git config --global --unset http.proxy`
仓库地址填写错误	使用命令 `git remote -v` 查看当前远程仓库地址是否正确；如有误，请使用 `git remote set-url origin <正确的地址>` 修改
分支名错误（如主分支为 `main` 而不是 `master`）	如果你的远程仓库默认分支是 `main`，请使用 `git push -u origin main` 替代 `git push -u origin master`；也可以通过 `git branch -M main` 将本地分支重命名为 `main` 后再推送
HTTPS 地址权限不足或认证失败	检查是否使用了正确的账号登录 Gitee；或者尝试使用 SSH 方式提交代码（需配置 SSH 密钥）
Git 版本过旧或系统时区设置异常	更新 Git 到最新版本；检查系统时间是否准确

🧪 补充调试命令：

查看远程仓库地址：
复制代码
```
bash
深色版本
git remote -v
```

修改远程仓库地址：

arduino 复制代码

bash
深色版本
git remote set-url origin https://gitee.com/你的用户名/仓库名.git

查看当前分支名称：
复制代码
```
bash
深色版本
git branch
```
更改本地分支名为 main：
css 复制代码
```
bash
深色版本
git branch -M main
```
清除 Git 全局代理（有时会导致连接失败）：
css 复制代码
```
bash
深色版本
git config --global --unset http.proxy
```
强制推送（谨慎使用）：
css 复制代码
```
bash
深色版本
git push -f origin main
```

💡 小贴士：

如果你在创建仓库时不小心勾选了"初始化 README"，最好删除本地 .git 目录并重新初始化。
如果你不确定远程仓库的主分支是 master 还是 main，可以在 Gitee 页面上查看默认分支名称。
使用 HTTPS 提交时，若提示用户名密码错误，建议使用 Gitee 的 Personal Access Token 替代密码（部分用户反馈 Gitee 已不再支持账号密码方式提交）。

✅ 总结

通过本文的指导，你应该能够：

安装 Composer 并设置国内镜像加速；
创建并配置一个 Composer 包；
将你的包推送到 Gitee；
在 Packagist 上提交你的包，并让其他人可以通过 Composer 安装使用。

如何一步步将自己的 PHP 包上传到 Packagist