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

如何一步步将自己的 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');"
步骤说明:
  1. 下载安装器:

    less 复制代码
    bash
    深色版本
    php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"
  2. 执行安装脚本:

    arduino 复制代码
    bash
    深色版本
    php composer-setup.php
  3. 删除临时文件:

    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 用户设置步骤:
  1. composer.phar 放入 PHP 安装目录下(如 C:\xampp\php)。

  2. 创建 composer.bat 文件,内容如下:

    css 复制代码
    深色版本
    @php "%~dp0composer.phar" %*
  3. 确保 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": "840960233@qq.com"
        }
    ],
    "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-stabilityprefer-stable 控制版本稳定性要求。
authors 定义作者信息。
license 定义使用的许可证类型。
repositories 自定义仓库地址。

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


第三步:将包上传到 Gitee

3.1 在 Gitee 上新建仓库

  1. 登录 gitee.com
  2. 点击右上角"+" → "新建仓库"
  3. 输入仓库名称(如 my-project
  4. 勾选"空仓库",不要勾选"初始化 README"
  5. 点击"创建"

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 账号

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

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

4.2 提交你的 Git 仓库地址

  1. 登录 packagist.org

  2. 点击右上角用户名 → "Submit"

  3. 在输入框中填写你的 Git 仓库地址(Gitee 或 GitHub 的 .git 地址)

    • 示例:

      perl 复制代码
      深色版本
      https://gitee.com/dzl/my-project.git
  4. 点击 "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 initgit add .git commitgit 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 安装使用。
相关推荐
苏琢玉8 天前
RSA+AES 混合加密不复杂,但落地挺烦,我用 Vue+PHP 封装成了两个库
vue.js·npm·php·composer
苏琢玉10 天前
一个轻量的PHP+Vue的前后端加密方案,写给有类似需求的朋友
php·composer
苏琢玉14 天前
订单号老是撞车?我写了个通用 PHP ID 生成器
php·composer
PyHaVolask1 个月前
PHP进阶语法详解:命名空间、类型转换与文件操作
开发语言·php·composer
苏琢玉1 个月前
如何优雅地处理多种电商优惠规则?我用 PHP 封装了一个 Promotion Engine
后端·php·composer
SHUIPING_YANG1 个月前
Composer 可以通过指定 PHP 版本运行
开发语言·php·composer
杰哥技术分享3 个月前
yii2基础版本安装记录,实录有点乱看标题即可
composer·yii
落华X3 个月前
windows安装多个版本composer
php·composer