composer.json 中出现 "Invalid version string" 错误是什么原因？

答案：版本号格式错误导致“Invalid version string”；需使用标准格式如1.2.3、^1.2.3，避免v前缀或不完整版本号。

在 composer.json 中出现 "Invalid version string" 错误，通常是因为版本号格式不符合 Composer 的规范。Composer 对依赖包的版本号有严格要求，如果写法不正确，就会抛出该错误。

1. 版本号拼写或格式错误

最常见的原因是手动输入版本号时出现了拼写错误或格式不合法。例如：

• ^1.0.0a —— 非标准写法，应使用正确的预发布标记
• v1.0.0 —— 前缀 v 是不允许的（某些包可能接受，但不推荐）
• 1.0 —— 缺少补丁版本号，建议写成 1.0.0
• ~1.0.0.1 —— 波浪符只能用于主版本或次版本，不能多级小数

确保使用 Composer 支持的版本约束格式，如：

• 1.2.3 —— 精确版本
• ^1.2.3 —— 兼容性约束（允许 1.x.x 中不破坏 API 的更新）
• ~1.2.3 —— 近似约束（等价于 >=1.2.3,

2. 使用了非法字符或空值

如果版本字段为空或包含特殊字符，也会导致解析失败：

• "version": "" —— 空字符串无效
• "version": "latest" —— latest 不是合法版本号
• "version": "dev-master#bad-branch-name!" —— 包含非法符号

注意：只有在定义自定义包时才需要显式写 version 字段，大多数项目不需要它，Composer 会从 Git 标签自动推断。

3. 分支名或开发版本写法错误

使用 dev 分支时，必须以 dev- 开头：

• "my/package": "master" —— 错误
• "my/package": "dev-master" —— 正确
• "my/package": "dev-develop as 1.5.0" —— 合法别名用法

同时确保分支名只包含字母、数字、连字符和点，不能有空格或特殊符号。

4. 自定义包中 version 字段不规范

如果你在 composer.json 中定义了 "type": "package" 或使用了 repositories 自定义包，必须确保 version 字段是有效的语义化版本（SemVer），例如：

• 1.0.0
• 2.1.3-beta
• 0.5.0-alpha.1

避免使用像 beta、stable、edge 这样的非标准值作为 version。

基本上就这些常见原因。检查你的依赖项版本写法是否符合规范，尤其是手写的部分。运行 composer validate 可帮助发现语法问题。修正后执行 composer install 或 update 即可解决。