version 字段仅在非 Git/SVN 项目中必须显式声明，用于覆盖 Composer 自动推断的版本；合法格式须为标准 SemVer（如"2.3.1"），禁用前缀或不完整写法；写入后将冻结版本信息，不再读取 Git 元数据。
Composer 的 version 字段不是用来“写版本号”的，而是用来覆盖包实际版本的元数据字段——绝大多数项目根本不需要手动写它。
什么时候必须写 version 字段？
仅当你的包未托管在 Git（或 SVN）中，且无法被 Composer 自动推断版本时才需显式声明。比如：打包一个纯 ZIP 发布的闭源组件、从私有 FTP 拉取的预编译库、或某些 CI 构建后生成的临时 dist 包。
- Git 仓库下，Composer 会自动读取
git describe --tags或最近 tag，version字段会被忽略 - 运行
composer install时若看到警告Package … is not installed as a dependency, but version is set in composer.json，说明你误写了该字段 - 在私有 Packagist（如 Satis/SatisPress）中发布非 VCS 包时，
version是唯一能告诉下游“这是 v2.1.0”的方式
version 字段的合法格式和常见错误
它必须是语义化版本（SemVer），但不支持带空格、斜杠或前缀的写法；Composer 不做语法校验，但解析失败会导致依赖解析中断或安装静默失败。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- ✅ 正确：
"version": "2.3.1"、"version": "dev-main"、"version": "1.0.0-beta.2" - ❌ 错误：
"version": "v2.3.1"（开头v会被当作分支名处理）、"version": "2.3.1-release"（非法 prerelease 格式）、"version": "2.3"（缺少补丁号，非标准 SemVer） - ⚠️ 特别注意：
"version": "dev-master"在现代 Composer 中已不推荐；应改用"branch-alias": {"dev-master": "2.x-dev"}配合稳定分支策略
替代方案：用 dist + version 实现离线发布
如果你真要分发无 VCS 的包（例如给内网客户交付 SDK），正确做法是构造完整 dist 描述，并确保 version 与压缩包文件名/URL 中的版本一致，否则 composer require 会报 Could not parse version constraint。
-
dist必须包含url（可为相对路径或 HTTP）、type（如zip）、shasum（校验用） -
version值必须严格匹配你期望用户require的版本约束，例如用户写"my/sdk": "^1.2"，则你的version得是"1.2.0"或更高 - 示例片段：
{
"name": "my/sdk",
"version": "1.2.3",
"dist": {
"url": "https://intranet.example.com/dist/my-sdk-1.2.3.zip",
"type": "zip",
"shasum": "a1b2c3..."
}
}
真正容易被忽略的是：一旦你写了 version，Composer 就不再尝试从 Git 获取真实 commit hash 或 tag 时间戳——所有版本信息都冻结在 JSON 里。下次更新不改这个字段，下游就永远看不到新版本。
