依赖管理与安全检查工作流 - Claude Code 工作流-学习笔记-上海佼艾

二、依赖声明管理

依赖声明文件是项目的"物料清单"，不同编程语言和生态有着各自的标准格式。Claude Code 需要理解并能够操作多种依赖声明格式，以提供跨语言的支持能力。下面逐一分析主流依赖声明文件的格式规范与最佳实践。

2.1 Node.js / JavaScript —— package.json

package.json 是 Node.js 生态的核心清单文件，记录了项目的元信息、依赖、脚本和配置。Claude Code 在处理 package.json 时需要特别关注语义化版本范围、依赖分组（dependencies 与 devDependencies）以及 scripts 字段中与依赖相关的钩子。

{
  "name": "my-express-app",
  "version": "1.0.0",
  "description": "企业级 Express 应用",
  "main": "dist/index.js",
  "scripts": {
    "preinstall": "npx only-allow pnpm",
    "postinstall": "patch-package",
    "audit": "npm audit --audit-level=high",
    "outdated": "npm outdated",
    "update:deps": "npx npm-check-updates -u && npm install"
  },
  "dependencies": {
    "express": "^4.18.2",
    "mongoose": "~7.6.3",
    "jsonwebtoken": "9.0.2",
    "helmet": "^7.1.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "jest": "^29.7.0",
    "eslint": "^8.56.0",
    "@types/express": "^4.17.21"
  },
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=8.0.0"
  }
}

语义化版本范围符号解析：^（caret）表示兼容主版本内的更新，~（tilde）表示只允许补丁版本更新，无符号则表示锁定精确版本。Claude Code 在自动更新时应当根据项目的版本策略选择合适的范围符号，避免无意间引入破坏性变更。

2.2 Python —— requirements.txt / Pipfile / pyproject.toml

Python 生态存在三种主要的依赖声明方式，Claude Code 需要根据项目实际使用的工具链选择对应的操作策略。requirements.txt 是最传统的格式，以简单直接的每行一个包名+版本约束著称，适合小型项目；Pipfile 是 Pipenv 引入的 TOML 格式声明文件，支持依赖分组（default 和 dev）；pyproject.toml 则是 PEP 621 规范推荐的新一代项目元数据标准。

# requirements.txt —— 传统格式
fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy>=2.0.23,<2.1.0
pydantic>=2.5.0
httpx~=0.25.2

# Pipfile —— Pipenv 格式
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
fastapi = "==0.104.1"
sqlalchemy = ">=2.0.23,<2.1.0"
pydantic = ">=2.5.0"

[dev-packages]
pytest = "==7.4.3"
pytest-cov = "==4.1.0"

[requires]
python_version = "3.11"

# pyproject.toml —— PEP 621 标准
[project]
name = "my-fastapi-app"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi==0.104.1",
    "sqlalchemy>=2.0.23,<2.1.0",
    "pydantic>=2.5.0",
    "httpx~=0.25.2",
]

[project.optional-dependencies]
dev = ["pytest==7.4.3", "pytest-cov==4.1.0"]
test = ["httpx==0.25.2", "pytest-asyncio==0.23.2"]

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

Claude Code 在操作 Python 依赖文件时的一个重要策略是优先使用 pyproject.toml（如果存在），因为这是 Python 社区的未来方向。同时，当检测到项目中同时存在 requirements.txt 和 pyproject.toml 时，应当提示用户两者可能存在不一致性。

2.3 Rust —— Cargo.toml

Rust 的 Cargo.toml 采用 TOML 格式，依赖声明支持多种形式：简单字符串、表格形式的完整配置（含 features、optional 等）。Cargo 的依赖解析器是业界公认最严格的之一，会在编译时确保所有依赖版本兼容。

[package]
name = "my-service"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
reqwest = { version = "0.11", features = ["json"], optional = true }
clap = { version = "4.4", features = ["derive"] }

[dev-dependencies]
tokio-test = "0.4"
criterion = { version = "0.5", features = ["html_reports"] }

[build-dependencies]
cc = "1.0"

[features]
default = ["http-client"]
http-client = ["dep:reqwest"]

Cargo.toml 中 optional = true 配合 [features] 可以实现条件编译，这是 Rust 生态特有的依赖优化手段。Claude Code 在分析 Rust 项目时应当检查 features 的传递性依赖是否符合预期，避免因特性组合引入不必要的编译负担。

2.4 Go —— go.mod

Go 模块的依赖管理以 go.mod 文件为核心，采用 Go 团队自研的 MVS（Minimal Version Selection）算法。go.mod 文件同时记录直接依赖和间接依赖（以 // indirect 注释标记），Claude Code 处理 go.mod 时需要关注 require 块的版本一致性。

module github.com/my-org/my-service go 1.21 require ( github.com/gin-gonic/gin v1.9.1 github.com/go-sql-driver/mysql v1.7.1 go.uber.org/zap v1.26.0 google.golang.org/grpc v1.60.1 gopkg.in/yaml.v3 v3.0.1 ) // replace 指令用于本地开发和依赖替换 replace github.com/old-package => github.com/new-package v1.0.0 // exclude 指令禁止特定版本 exclude github.com/broken-package v0.9.0

go.mod 中的 replace 和 exclude 指令是 Go 生态独有的版本控制工具。replace 可用于将已废弃的包重定向到新路径，或本地开发时替换为本地路径。Claude Code 应当提醒用户注意 replace 指令不要被误提交到生产环境。

三、依赖更新策略

依赖更新是一个需要权衡安全性与稳定性的复杂决策。过于激进的更新可能导致兼容性问题，过于保守的更新则可能使项目暴露在已知漏洞中。Claude Code 应当根据项目特征和团队策略，提供可配置的依赖更新方案。

3.1 自动更新策略

对于补丁版本和次版本更新，可以采用自动化流程处理。Claude Code 通过分析当前版本与最新版本之间的 changelog 和 breaking changes 来判断更新的风险等级。低风险的更新可以自动创建 PR，高风险的更新则需要人工审核。

# Claude Code 自动检测更新脚本示例
#!/bin/bash
# check-deps.sh —— 依赖更新检测与风险评估

echo "=== 依赖更新检测 ==="

# 检测 package.json 更新
if [ -f "package.json" ]; then
    echo "--- Node.js 依赖 ---"
    npx npm-check-updates --format group
    npm outdated

    # 自动更新补丁版本
    npx npm-check-updates -u --target patch
    npm install --no-audit --no-fund
fi

# 检测 Python 依赖更新
if [ -f "pyproject.toml" ]; then
    echo "--- Python 依赖 ---"
    pip install pip-upgrader
    pip-upgrade

    # 使用 pip-audit 检查更新后的安全状态
    pip-audit
fi

# 检测 Go 模块更新
if [ -f "go.mod" ]; then
    echo "--- Go 模块 ---"
    go list -u -m all | grep '\['
    go mod tidy
fi

echo "=== 检测完成 ==="

3.2 版本锁定策略

在生产环境中，依赖版本锁定是保证可复现构建的基础。Claude Code 应当根据项目类型推荐合适的版本锁定策略：对于前端项目推荐使用 yarn.lock 或 pnpm-lock.yaml，对于后端 Python 项目推荐 Pipfile.lock 或 poetry.lock，对于 Go 项目则依赖 go.sum 文件。

3.3 兼容性矩阵

当项目同时依赖多个相关包（如 React + React-DOM，或者多个 AWS SDK 包）时，Claude Code 需要验证这些依赖之间的版本兼容性。兼容性矩阵可以通过交叉引用各包的 peerDependencies 或官方兼容性文档来实现。

# compatibility-check.sh —— 依赖兼容性矩阵检查
#!/bin/bash

echo "=== 兼容性矩阵检查 ==="

check_compatibility() {
    local pkg=$1
    local version=$2
    local peer_pkg=$3

    # 获取 peerDependencies
    peer_version=$(npm view "$pkg@$version" peerDependencies."$peer_pkg" 2>/dev/null)
    if [ -n "$peer_version" ]; then
        echo "[检查] $pkg@$version 需要 $peer_pkg@$peer_version"

        # 验证当前安装的版本是否满足要求
        installed_version=$(npm list "$peer_pkg" --depth=0 2>/dev/null | grep "$peer_pkg@" | sed 's/.*@//')
        if [ -n "$installed_version" ]; then
            if npx semver -r "$peer_version" "$installed_version" &>/dev/null; then
                echo "  ✓ 兼容"
            else
                echo "  ✗ 不兼容！需要 $peer_version，当前为 $installed_version"
            fi
        fi
    fi
}

# 检查 React 生态兼容性
check_compatibility "react" "18.2.0" "react-dom"
check_compatibility "react-dom" "18.2.0" "react"

# 检查 TypeScript 与 @types 包兼容性
check_compatibility "typescript" "5.3.0" "@types/node"

3.4 大版本升级策略

主版本升级（Major Version Upgrade）是风险最高的依赖变更操作。Claude Code 在进行大版本升级时应遵循以下步骤：首先阅读升级指南和 Breaking Changes 文档，然后识别需要修改的 API 调用点，接着在隔离分支上进行升级和测试，最后逐步灰度发布。以下是大版本升级的标准工作流。

# major-upgrade-workflow.sh —— 大版本升级标准工作流
#!/bin/bash

PKG_NAME=$1
CURRENT_VER=$(npm list "$PKG_NAME" --depth=0 2>/dev/null | grep "$PKG_NAME@" | sed 's/.*@//')
LATEST_VER=$(npm view "$PKG_NAME" version)

echo "=== 大版本升级工作流 ==="
echo "包名: $PKG_NAME"
echo "当前版本: $CURRENT_VER"
echo "最新版本: $LATEST_VER"

# 步骤1：创建升级分支
git checkout -b "upgrade/$PKG_NAME-$LATEST_VER"

# 步骤2：查看 Breaking Changes
npm view "$PKG_NAME" deprecation  # 检查是否已废弃
npm view "$PKG_NAME" engine        # 检查 Node.js 版本要求

# 步骤3：执行升级
npm install "$PKG_NAME@latest"

# 步骤4：运行全部测试
npm run test:ci
npm run build

# 步骤5：如果测试失败则回滚
if [ $? -ne 0 ]; then
    echo "测试失败，正在回滚..."
    git checkout -- .
    git checkout main
    git branch -D "upgrade/$PKG_NAME-$LATEST_VER"
    exit 1
fi

echo "升级完成，请审查变更并创建 PR"

3.5 废弃包替代方案

Claude Code 应当维护一份常用废弃包及其替代品的映射表。当检测到项目正在使用已废弃的包时，自动建议替代方案并生成迁移指南。

已废弃包	替代方案	废弃原因	迁移难度
request	node-fetch / axios / undici	作者已停止维护	中等
moment.js	day.js / date-fns / luxon	体积过大，Tree Shaking 困难	低
gulp	Vite / esbuild / Webpack 5	流式构建已被现代工具取代	高
faker.js	@faker-js/faker	原作者删除仓库后的社区接管版	低
colors.js	chalk / picocolors	供应链投毒事件	低
npm	pnpm / yarn 4	性能与安全性	中等

注意：当 Claude Code 检测到项目依赖已废弃的包时，应当立即发出告警并标记为高优先级任务。废弃包不会接收安全更新，可能成为供应链攻击的入口。

四、安全漏洞扫描

安全漏洞扫描是依赖管理中最关键的环节。随着近年来 SolarWinds、Log4Shell 等重大供应链安全事件的发生，业界对依赖安全性的关注达到了前所未有的高度。Claude Code 可以集成多种扫描工具，构建多层次的漏洞检测体系。

4.1 npm audit —— Node.js 原生审计

npm audit 是 Node.js 生态内置的安全审计工具，会查询 npm 公开漏洞数据库，为项目中的每个依赖标注已知 CVE。Claude Code 可以调用 npm audit 并解析其 JSON 输出，生成结构化的安全报告。

# npm audit 深度执行与结果解析
npm audit --json 2>/dev/null | node -e "
const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
const summary = {
  critical: 0,
  high: 0,
  moderate: 0,
  low: 0,
  total: 0,
  fixable: 0,
  advisoryDetails: []
};

for (const [id, advisory] of Object.entries(data.advisories || {})) {
  summary.total++;
  summary[advisory.severity]++;
  if (advisory.findFixedPath) summary.fixable++;
  summary.advisoryDetails.push({
    id: advisory.id,
    cve: advisory.cves[0] || 'N/A',
    severity: advisory.severity,
    title: advisory.title,
    package: advisory.module_name,
    vulnerableVersions: advisory.vulnerable_versions,
    patchedVersions: advisory.patched_versions,
    cvss: advisory.cvss?.score || 'N/A'
  });
}

console.log('=== 漏洞汇总 ===');
console.log('总计:', summary.total);
console.log('严重:', summary.critical);
console.log('高危:', summary.high);
console.log('中危:', summary.moderate);
console.log('低危:', summary.low);
console.log('可修复:', summary.fixable);
console.log('\\n=== 详细信息 ===');
summary.advisoryDetails.forEach(a => {
  console.log(a.severity.toUpperCase(), '|', a.cve, '|', a.package, '|', a.title);
});
"

4.2 pip audit —— Python 安全审计

对于 Python 项目，Claude Code 可以使用 pip-audit 工具扫描 PyPI 依赖的已知漏洞。pip-audit 支持多种输入格式（requirements.txt、pyproject.toml、Pipfile.lock），并将结果与 Python Packaging Advisory Database 进行比对。

# pip audit —— Python 依赖安全扫描
# 安装并执行
pip install pip-audit
pip-audit --requirement requirements.txt --format=json | python -c "
import json, sys

data = json.load(sys.stdin)
print('=== Python 依赖安全扫描报告 ===')
print(f'检查依赖数: {data[\"audited_dependencies_count\"]}')

# 按严重性分组
vulns = {}
for dep in data.get('dependencies', []):
    for vuln in dep.get('vulnerabilities', []):
        sev = vuln.get('severity', 'unknown')
        vulns.setdefault(sev, []).append(vuln)

for sev in ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']:
    items = vulns.get(sev.lower(), [])
    if items:
        print(f'\\n[{sev}] {len(items)} 个漏洞')
        for v in items:
            vuln_id = v.get('id', 'N/A')
            pkg = v.get('package', {}).get('name', 'N/A')
            print(f'  {vuln_id} → {pkg}')

# 生成修复建议
print('\\n=== 修复建议 ===')
for dep in data.get('dependencies', []):
    for vuln in dep.get('vulnerabilities', []):
        fixed_ver = vuln.get('fixed_version', 'N/A')
        if fixed_ver != 'N/A':
            print(f'升级 {dep[\"name\"]} 至 {fixed_ver}')
"

4.3 Dependabot —— GitHub 原生自动化

Dependabot 是 GitHub 内置的依赖更新和漏洞修复工具。Claude Code 可以通过 GitHub API 检索 Dependabot 告警，并在本地开发环境中同步分析结果。配置 Dependabot 的核心是 .github/dependabot.yml 文件。

# .github/dependabot.yml —— Dependabot 完整配置
version: 2
updates:
  # npm 依赖更新
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
      timezone: "Asia/Shanghai"
    open-pull-requests-limit: 10
    versioning-strategy: increase
    labels:
      - "dependencies"
      - "npm"
    commit-message:
      prefix: "deps"
      prefix-development: "deps(dev)"

    # 允许的更新类型
    allow:
      - dependency-type: "direct"
      - dependency-type: "indirect"

    # 忽略特定类型的更新
    ignore:
      - dependency-name: "react"
        versions: [">=19.0.0"]
      - dependency-name: "typescript"
        versions: [">=6.0.0"]

    # 为每个依赖创建独立的 PR
    pull-request-branch-name:
      separator: "-"

    # 自动 rebase
    rebase-strategy: "auto"

  # Python 依赖更新
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    labels:
      - "dependencies"
      - "python"

  # Docker 镜像更新
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "monthly"

4.4 Snyk —— 商业级漏洞扫描平台

Snyk 提供比 npm audit 更全面的漏洞检测，包括对传递依赖的深度扫描、开源许可证合规性检查以及容器镜像扫描。Claude Code 可以通过 Snyk CLI 在 CI/CD 管道中集成扫描步骤。

# Snyk CLI 集成执行
# 安装: npm install -g snyk

# 认证
snyk auth $SNYK_TOKEN

# 全量扫描
snyk test --all-projects --severity-threshold=medium --json > snyk-report.json

# 监控项目（持续跟踪新漏洞）
snyk monitor --all-projects --org=my-org

# 容器镜像扫描
snyk container test node:20-alpine --json

# 生成 HTML 报告
snyk-to-html -i snyk-report.json -o snyk-report.html

# CI 集成 —— 失败时阻断构建
snyk test --all-projects --severity-threshold=high || {
    echo "发现高危漏洞，构建失败"
    exit 1
}

4.5 Grype + Trivy —— 开源漏洞扫描

Grype 和 Trivy 是两款优秀的开源漏洞扫描工具，支持多种包格式和操作系统组件扫描。Claude Code 可以将二者作为成本敏感型项目的首选方案。

# Grype 扫描（Anchore 出品）
# 安装: curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin

# 扫描 Node.js 项目
grype dir:. --only-fixed --severity high,critical -o json > grype-report.json

# 扫描 Python 项目（指定 sbom）
grype cyclonedx:sbom.json -o table

# 扫描容器镜像
grype alpine:latest --only-fixed --fail-on high

# Trivy 扫描（Aqua Security 出品）
# 安装: curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

# 扫描文件系统
trivy fs . --severity CRITICAL,HIGH --no-progress --format json -o trivy-report.json

# 扫描容器镜像
trivy image node:20-alpine --severity CRITICAL --ignore-unfixed

# 生成 SBOM
trivy fs . --format cyclonedx --output sbom.cdx.json

# 扫描 IaC 配置文件
trivy config . --severity HIGH

4.6 CVE 查询与严重性分级

Claude Code 可以直接查询 NVD（National Vulnerability Database）的公开漏洞信息，并为扫描结果补充 CVSS 评分和 EPSS（Exploit Prediction Scoring System）概率，帮助团队优先修复最紧迫的漏洞。

严重等级	CVSS 分数范围	修复时限	响应策略
CRITICAL	9.0 - 10.0	24 小时内	立即修复或回退依赖版本
HIGH	7.0 - 8.9	7 天内	创建紧急修复 PR
MEDIUM	4.0 - 6.9	30 天内	纳入下一个迭代计划
LOW	0.1 - 3.9	90 天内	定期评审，按需修复

最佳实践：Claude Code 应当在每次代码提交前自动运行安全扫描，并将扫描结果作为 PR 审查的一部分。对于 CRITICAL 级别的漏洞，可自动阻断合并操作。

五、许可证合规检查

开源许可证合规性是企业在使用第三方依赖时容易忽视的法律风险。Claude Code 可以自动化许可证检查流程，帮助团队避免因意外引入 Copyleft 许可证而导致的商业纠纷。

5.1 license-checker 与 SPDX 标识

SPDX（Software Package Data Exchange）是业界标准的许可证标识格式。Claude Code 利用 license-checker（Node.js）或 pip-licenses（Python）等工具扫描项目依赖的许可证类型，并与 SPDX 标识列表进行比对。

# license-checker —— Node.js 许可证审计
npx license-checker --json --production --excludePrivatePackages > licenses.json

npx license-checker --json --production --excludePrivatePackages | node -e "
const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));

const licenseGroups = {};
const APPROVED_LICENSES = [
  'MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause',
  'ISC', 'Unlicense', 'CC0-1.0', '0BSD'
];
const RESTRICTED_LICENSES = ['GPL-2.0', 'GPL-3.0', 'AGPL-3.0', 'LGPL-3.0'];

for (const [pkg, info] of Object.entries(data)) {
  const license = info.licenses;
  licenseGroups[license] = (licenseGroups[license] || 0) + 1;

  if (RESTRICTED_LICENSES.includes(license)) {
    console.log('[限制]', license, '→', pkg, '|', info.repository);
    console.log('  路径:', info.path);
  }
}

console.log('\\n=== 许可证分布 ===');
for (const [license, count] of Object.entries(licenseGroups).sort((a,b) => b[1]-a[1])) {
  const status = APPROVED_LICENSES.includes(license) ? '✓' :
                 RESTRICTED_LICENSES.includes(license) ? '⚠' : '?';
  console.log(status, license, ':', count, '个包');
}
"

5.2 GPL/AGPL 兼容性分析

GPL 和 AGPL 系列许可证具有"Copyleft"特性，要求派生作品也必须以相同许可证发布。Claude Code 在检测到项目使用了 GPL/AGPL 依赖时，应当发出明确警告并分析兼容性风险。对于商业闭源项目，使用 GPL 依赖可能意味着整个项目需要开源。

5.3 商业许可与未授权依赖

部分开源包采用商业许可证（如 Commons Clause、SSPL、Elastic License 2.0），或者完全没有声明许可证（即"Orphaned Dependency"）。Claude Code 应当标记这些包并建议团队联系作者澄清授权条款。

# Python 依赖许可证检查
pip install pip-licenses
pip-licenses --format=json --with-urls --with-authors --with-system --with-description | python -c "
import json, sys

data = json.load(sys.stdin)
issues = []

for pkg in data:
    license = pkg.get('License', '').strip()
    name = pkg.get('Name', '')
    url = pkg.get('URL', '')

    # 检查未授权依赖
    if not license or license == 'UNKNOWN':
        issues.append({
            'type': 'NO_LICENSE',
            'package': name,
            'url': url,
            'message': f'{name} 没有声明许可证，存在法律风险'
        })

    # 检查商业许可证
    restricted = ['SSPL', 'Elastic License 2.0', 'Commons Clause', 'BSL-1.1']
    for r in restricted:
        if r.upper() in license.upper():
            issues.append({
                'type': 'RESTRICTED_LICENSE',
                'package': name,
                'license': license,
                'message': f'{name} 使用 {license}，可能不适用于商业闭源项目'
            })

# 输出报告
print('=== 许可证合规检查报告 ===')
print(f'总依赖数: {len(data)}')
print(f'问题数: {len(issues)}')
print()

for issue in issues:
    print(f'[{issue[\"type\"]}] {issue[\"package\"]}')
    print(f'  {issue[\"message\"]}')
    print()

if not issues:
    print('✓ 未发现问题，所有依赖的许可证均合规')
"

法律声明：本工作流提供的许可证分析仅供参考，不构成法律建议。企业在使用第三方依赖前应当咨询法务部门或专业知识产权律师，以确认许可证条款与商业目标的兼容性。

六、依赖优化

依赖优化不仅关注安全性，还关注项目的性能、体积和可维护性。过多的依赖或过大的依赖包会拖慢构建速度、增加攻击面并降低运行时性能。Claude Code 可以通过自动化分析帮助团队"瘦身"依赖清单。

6.1 未使用依赖检测

项目在长期迭代过程中容易积累不再使用的依赖。Claude Code 可以借助 depcheck、knip 等工具扫描代码库，识别出声明了但从未 import 的"僵尸依赖"。

# depcheck —— 未使用依赖检测
npx depcheck --json --ignores='@types/*,eslint-plugin-*' | node -e "
const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));

if (data.dependencies.length > 0) {
  console.log('=== 未使用的生产依赖 ===');
  data.dependencies.forEach(dep => console.log('  ✗', dep));
}

if (data.devDependencies.length > 0) {
  console.log('\\n=== 未使用的开发依赖 ===');
  data.devDependencies.forEach(dep => console.log('  ✗', dep));
}

if (data.missing.length > 0) {
  console.log('\\n=== 缺失依赖 ===');
  data.missing.forEach(dep => {
    console.log('  !', dep);
  });
}

console.log('\\n=== 总结 ===');
console.log('未使用生产依赖:', data.dependencies.length);
console.log('未使用开发依赖:', data.devDependencies.length);
console.log('缺失依赖:', data.missing.length);

if (data.dependencies.length + data.devDependencies.length === 0) {
  console.log('✓ 依赖清单整洁');
}
"

6.2 重复依赖检测

当项目中多个包依赖了同一个包的不同版本时，会导致"重复打包"问题，增加最终产物的体积。Claude Code 可以使用 npm dedupe、pnpm dedupe 或 yarn-deduplicate 来消除重复依赖。

# 重复依赖检测与消除

# npm 的 dedupe 命令
npx npm dedupe --dry-run
npm ls --all --json | node -e "
const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
const seen = new Map();

function walk(tree, path) {
  const name = tree.name || tree.label;
  const version = tree.version;
  if (name && version) {
    const key = name;
    if (seen.has(key) && seen.get(key) !== version) {
      console.log('[重复]', name, '| 版本:', seen.get(key), '和', version);
      console.log('  路径:', path);
    }
    seen.set(key, version);
  }
  if (tree.dependencies) {
    Object.entries(tree.dependencies).forEach(([depName, dep]) => {
      walk(dep, [...path, depName]);
    });
  }
}
walk(data, []);

// pnpm 用户
pnpm dedupe --check

// yarn 用户
npx yarn-deduplicate yarn.lock --list

6.3 依赖瘦身策略

依赖瘦身的目标是在不损失功能的前提下最小化依赖体积。Claude Code 可以推荐以下实践：使用树摇（Tree Shaking）友好的子路径导入替代全量导入，将大型工具库替换为小型专用库，以及使用构建时优化移除未使用的导出。

// 依赖瘦身 —— 最佳实践示例

// ❌ 不推荐：全量导入 lodash
import _ from 'lodash';
_.get(obj, 'path');

// ✅ 推荐：按需导入 lodash 函数
import get from 'lodash/get';
get(obj, 'path');

// 或者使用 lodash-es（支持 Tree Shaking）
import { get } from 'lodash-es';

// ❌ 不推荐：全量导入 date-fns
import { format } from 'date-fns';
format(new Date(), 'yyyy-MM-dd');

// ✅ 推荐：按需导入 date-fns 函数
import format from 'date-fns/format';
format(new Date(), 'yyyy-MM-dd');

// ❌ 不推荐：使用 moment.js（体积 ~300KB）
import moment from 'moment';

// ✅ 推荐：使用 day.js（体积 ~2KB）
import dayjs from 'dayjs';

// ❌ 不推荐：全量导入 Ant Design 图标
import { HomeOutlined, UserOutlined } from '@ant-design/icons';

// ✅ 推荐：从子路径单独导入
import HomeOutlined from '@ant-design/icons/HomeOutlined';
import UserOutlined from '@ant-design/icons/UserOutlined';

6.4 可选依赖与 peerDependencies

Claude Code 应当指导开发者正确使用 optionalDependencies 和 peerDependencies。optionalDependencies 用于非核心功能的基础设施（如可选的日志收集器），而 peerDependencies 用于声明宿主环境必须提供的依赖（如 React 插件的 React 版本要求）。

{
  "name": "my-ui-plugin",
  "version": "2.0.0",

  "dependencies": {
    "clsx": "^2.1.0",
    "tiny-warning": "^1.0.3"
  },

  "peerDependencies": {
    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
  },

  "peerDependenciesMeta": {
    "react-dom": {
      "optional": true
    }
  },

  "optionalDependencies": {
    "@rollup/rollup-linux-x64-gnu": "^4.0.0"
  }
}

提示：Claude Code 在分析 package.json 时应当检查 peerDependencies 是否已在宿主项目中正确安装。缺失的 peerDependencies 会导致运行时错误，且容易被开发者在日常开发中忽略。

七、依赖锁定

依赖锁定文件是实现可复现构建的关键保障。锁定文件记录了每个依赖的确切版本以及传递依赖的解析结果，确保不同开发环境和 CI 服务器上安装的依赖完全一致。

7.1 主流锁定文件格式

生态	锁定文件	格式	自动生成	是否应提交
npm	package-lock.json	JSON	npm install	是
yarn	yarn.lock	YAML 风格	yarn install	是
pnpm	pnpm-lock.yaml	YAML	pnpm install	是
Pipenv	Pipfile.lock	JSON	pipenv lock	是
Poetry	poetry.lock	TOML	poetry lock	是
Cargo	Cargo.lock	TOML	cargo build	是（应用项目）
Go	go.sum	文本	go mod tidy	是

7.2 yarn.lock / pnpm-lock.yaml 解析

yarn.lock 和 pnpm-lock.yaml 内部记录了所有依赖的精确版本、解析地址和完整性哈希。Claude Code 可以通过解析锁定文件来验证依赖版本是否满足项目要求，以及检测意外的传递依赖版本变更。

# lockfile-verify.sh —— 锁定文件验证脚本
#!/bin/bash

echo "=== 锁定文件验证 ==="

# 检查 package-lock.json 完整性
if [ -f "package-lock.json" ]; then
    echo "--- npm lockfile 验证 ---"
    npm ci --dry-run 2>&1 | tail -5

    # 检查锁定文件版本一致性
    node -e "
    const lock = require('./package-lock.json');
    console.log('lockfileVersion:', lock.lockfileVersion);
    console.log('总条目:', Object.keys(lock.packages || {}).length);
    "
fi

# 检查 pnpm-lock.yaml 完整性
if [ -f "pnpm-lock.yaml" ]; then
    echo "--- pnpm lockfile 验证 ---"
    pnpm install --frozen-lockfile --dry-run 2>&1 | tail -5

    # 验证锁定文件是否与 package.json 同步
    pnpm audit --prod
fi

# 检查 go.sum 完整性
if [ -f "go.sum" ]; then
    echo "--- Go sum 验证 ---"
    go mod verify
fi

# 检查 Pipfile.lock 完整性
if [ -f "Pipfile.lock" ]; then
    echo "--- Pipenv lockfile 验证 ---"
    pipenv verify
fi

echo "=== 验证完成 ==="

7.3 .gitignore 锁定文件策略

关于锁定文件是否应该提交到版本控制，业界存在不同观点。Claude Code 的推荐策略是：对于应用程序项目，锁定文件应当提交到版本控制以实现可复现构建；对于库/包项目，锁定文件可以忽略，因为用户会根据自身的依赖解析结果来安装。

# .gitignore —— 推荐锁定文件策略

# 应用程序项目（提交锁定文件）
# 不要将以下行取消注释：
# package-lock.json
# yarn.lock
# pnpm-lock.yaml

# 库/包项目（忽略锁定文件）
# 取消以下行的注释：
# package-lock.json
# yarn.lock
# pnpm-lock.yaml

# 始终忽略的文件
*.tsbuildinfo
dist/
node_modules/
.cache/
coverage/

# 环境相关
.env
.env.local
.env.production

最佳实践：Claude Code 应当检测项目中是否存在锁定文件与包声明文件之间的不一致性。例如，如果 package.json 中定义了一个版本范围而 package-lock.json 中的解析版本不在该范围内，应当发出警告并建议执行 npm install 来同步锁定文件。

八、工作流集成与自动化

将以上各个独立环节集成为一个完整的自动化工作流，是 Claude Code 在依赖管理领域的核心价值。下面展示一个完整的 CI/CD 集成方案，将所有检查步骤串联到 GitHub Actions 中。

8.1 完整的 CI 管道配置

# .github/workflows/dependency-security-check.yml
name: 依赖管理与安全检查

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨2点

jobs:
  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: 设置 Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: 安装依赖
        run: |
          npm install -g pnpm
          pnpm install --frozen-lockfile
          pip install pip-audit

      - name: 安全漏洞扫描
        run: |
          echo "=== npm audit ==="
          pnpm audit --audit-level=high || true

          echo "=== Snyk 扫描 ==="
          snyk test --severity-threshold=high || snyk monitor

          echo "=== Python 安全审计 ==="
          pip-audit --requirement requirements.txt || true

      - name: 许可证合规检查
        run: |
          echo "=== license-checker ==="
          npx license-checker --production --failOn 'GPL-3.0;AGPL-3.0'

      - name: 未使用依赖检测
        run: |
          echo "=== depcheck ==="
          npx depcheck --json || true

      - name: 检查锁定文件一致性
        run: |
          pnpm install --frozen-lockfile
          echo "锁定文件一致性检查通过"

      - name: 生成综合报告
        if: always()
        run: |
          echo "=== 依赖管理综合报告 ==="
          echo "检查时间: $(date)"
          echo "分支: ${{ github.ref }}"
          echo "提交: ${{ github.sha }}"
          echo ""
          echo "检查项:"
          echo "  1. 依赖声明完整性 ✓"
          echo "  2. 安全漏洞扫描 ✓"
          echo "  3. 许可证合规 ✓"
          echo "  4. 未使用依赖检测 ✓"
          echo "  5. 锁定文件一致性 ✓"

      - name: 阻断高危漏洞合并
        if: failure()
        run: |
          echo "安全检查未通过，请修复上述问题后再合并"
          exit 1

8.2 Claude Code 自动化提示词

以下是 Claude Code 的一键式依赖管理工作流提示词模板，团队可以直接复制使用。

# Claude Code 依赖管理一键式提示词

## 全量检查提示词
"""
执行全面的依赖管理与安全检查：
1. 扫描所有依赖声明文件（package.json / pyproject.toml / Cargo.toml / go.mod）
2. 检查是否有版本过期的依赖，列出需要更新的包
3. 运行安全漏洞扫描，按严重性分级报告
4. 检查许可证合规性
5. 检测未使用的依赖
6. 验证锁定文件一致性
7. 生成 Markdown 格式的依赖管理报告
"""

## 安全修复提示词
"""
分析 npm audit 的输出，对于所有可修复的高危及以上漏洞：
1. 列出每个漏洞的 CVE 编号、影响版本和修复版本
2. 评估每个修复的兼容性风险
3. 创建升级这些依赖的代码修改
4. 如果修复可能引入 Breaking Changes，标注需要人工审查
5. 输出最终的依赖状态和修复摘要
"""

## 依赖瘦身提示词
"""
对当前项目的依赖进行瘦身分析：
1. 列出所有未使用的依赖
2. 检查是否存在大型依赖可以替换为轻量级替代
3. 分析 bundle 体积，找出占比最大的依赖
4. 检查是否有重复依赖可以 dedupe
5. 给出具体的优化建议和预期节省的体积
"""

九、核心要点总结

依赖声明管理：Claude Code 需要支持 package.json、pyproject.toml、Cargo.toml、go.mod、requirements.txt 等多种格式，理解各生态的版本约束语义。
更新策略分层：补丁版本自动化更新、次版本定期更新、主版本升级需专人审查。Claude Code 根据风险评估自动推荐更新策略。
多层次安全扫描：结合 npm audit/pip audit（基础层）、Dependabot（自动化层）、Snyk（商业增强层）、Grype/Trivy（开源补充层）构建纵深防御体系。
许可证合规：自动化检查 Copyleft 许可证（GPL/AGPL）、商业许可证和未授权依赖，降低法律风险。
依赖优化持续进行：定期使用 depcheck 和 knip 清理僵尸依赖，通过 Tree Shaking 和轻量级替代降低项目体积。
锁定文件是基石：提交锁定文件到版本控制是实现可复现构建的前提，CI 中使用 frozen-lockfile 模式确保一致性。
供应链安全：废弃包和未维护的依赖是供应链攻击的主要入口，Claude Code 应当主动检测并推荐替代方案。
自动化集成：将整个工作流封装为 CI/CD 管道或 Claude Code 提示词模板，实现"一键执行"的依赖管理体验。

十、进一步思考

依赖管理与安全检查不仅仅是技术问题，更涉及到组织管理、风险控制和合规治理等多个维度。随着开源生态的日益复杂和供应链攻击的持续演进，依赖管理正在从"开发者的可选任务"演变为"组织的必选项"。未来，SBOM（Software Bill of Materials）将成为软件交付的标准组成部分，而 AI 驱动的自动化工具将在依赖管理的全生命周期中扮演越来越重要的角色。

Claude Code 作为 AI 开发助手，在依赖管理领域的价值不仅体现在自动化执行上，更体现在对依赖关系的深度理解、对安全风险的智能评估以及对最佳实践的持续推荐上。通过将本工作流纳入团队的日常开发流程，可以系统性地提升项目的安全基线、降低维护成本、加速交付周期。

扩展方向：未来依赖管理工作流可以进一步集成容器镜像扫描（Docker Scout / Trivy）、基础设施即代码（IaC）安全检查（Checkov / tfsec）以及运行时依赖监控功能，构建从开发到生产的全链路依赖安全保障体系。

一、工作流概述