How do you diagnose and debug npm issues and what are common troubleshooting techniques? - 面试题

npm provides various diagnostic and debugging tools to help developers solve package management related issues. Mastering these tools can significantly improve troubleshooting efficiency.

npm Diagnostic Commands

npm doctor

npm doctor checks the health of the npm environment and identifies potential issues.

bash
# Run diagnostics
npm doctor

# Check specific aspects
npm doctor --registry
npm doctor --network
npm doctor --permissions

Output Example:

shell
npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /Users/user/.npm/_cacache/index-v5/
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory

npm config diagnose

Diagnose configuration issues:

bash
# View configuration
npm config list

# View specific configuration
npm config get registry

# View configuration file locations
npm config get userconfig
npm config get globalconfig
npm config get projectconfig

Common Issue Diagnostics

1. Installation Failures

Issue: Network Problems

bash
# Check network connection
ping registry.npmjs.org

# Check proxy settings
npm config get proxy
npm config get https-proxy

# Use mirror
npm config set registry https://registry.npmmirror.com

Issue: Permission Problems

bash
# Check permissions
ls -la ~/.npm

# Fix permissions
sudo chown -R $(whoami) ~/.npm

# Set user in npm config
npm config set user $(whoami)

Issue: Cache Problems

bash
# Clean cache
npm cache clean --force

# Verify cache
npm cache verify

# Reinstall
rm -rf node_modules package-lock.json
npm install

2. Dependency Conflicts

Issue: Peer Dependency Conflicts

bash
# View dependency tree
npm ls

# View dependencies of specific package
npm ls <package>

# Use strict mode
npm config set strict-peer-deps true

# Force install
npm install --force

Issue: Version Conflicts

bash
# View outdated packages
npm outdated

# Update packages
npm update

# Use overrides
npm config set overrides '{"package": "1.2.3"}'

3. Lock File Issues

Issue: Corrupted package-lock.json

bash
# Delete lock file
rm package-lock.json

# Reinstall
npm install

# Use npm ci
npm ci

Issue: Inconsistent Lock File

bash
# View differences
npm diff

# Regenerate lock file
rm package-lock.json
npm install

4. Script Execution Issues

Issue: Script Not Found

bash
# View all scripts
npm run

# Check script syntax
cat package.json | grep scripts

# Use full path
npm run /path/to/script.js

Issue: Environment Variable Issues

bash
# View environment variables
npm run <script> --verbose

# Set environment variables
export NODE_ENV=production
npm run build

# Use environment variables in scripts

Advanced Diagnostic Tools

1. npm explain

Explain why a package is installed:

bash
# Explain installation reason for package
npm explain <package>

# View dependency tree
npm explain <package> --json

Output Example:

shell
express@4.18.2
node_modules/express
  express@"^4.18.0" from the root project

2. npm query

Query dependency information:

bash
# Query all outdated packages
npm query ":outdated"

# Query all dev dependencies
npm query ":dev"

# Query dependencies of specific package
npm query "lodash > *"

# Query dependency paths
npm query "#./packages/*"

3. npm diff

Compare dependency versions:

bash
# Compare current installation with package.json
npm diff

# Compare specific package
npm diff <package>

# Compare two versions
npm diff <package>@1.0.0 <package>@2.0.0

4. npm ls

View installed packages:

bash
# View all packages
npm ls

# View top-level dependencies
npm ls --depth=0

# View specific package
npm ls <package>

# Output in JSON format
npm ls --json

# View global packages
npm ls --global

Debugging Techniques

1. Enable Verbose Logging

bash
# Set log level
npm config set loglevel verbose

# Run command
npm install --verbose

# Set to debug level
npm config set loglevel silly

2. Use Debug Flags

bash
# Enable debugging
npm install --dd

# Enable verbose debugging
npm install --ddd

# View network requests
npm install --loglevel=http

3. View Installation Logs

bash
# View log files
cat ~/.npm/_logs/*.log

# View latest logs
tail -f ~/.npm/_logs/*.log

# Search for errors
grep -i error ~/.npm/_logs/*.log

4. Use npm debug

bash
# Enable debug mode
DEBUG=* npm install

# Enable debugging for specific modules
DEBUG=npm:* npm install

# Enable network debugging
DEBUG=npm:request npm install

Performance Diagnostics

1. Slow Installation Speed

bash
# Check network speed
ping registry.npmjs.org

# Use mirror
npm config set registry https://registry.npmmirror.com

# Increase parallelism
npm config set maxsockets 50
npm config set network-concurrency 16

# Use cache
npm install --prefer-offline

2. Disk Space Issues

bash
# View disk usage
du -sh ~/.npm
du -sh node_modules

# Clean cache
npm cache clean --force

# Use pnpm to save space
npm install -g pnpm

3. Memory Issues

bash
# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Use npm ci
npm ci

# Install in batches
npm install --no-package-lock

Security Diagnostics

1. Security Vulnerabilities

bash
# Run security audit
npm audit

# View vulnerability details
npm audit --json

# Fix vulnerabilities
npm audit fix

# Force fix
npm audit fix --force

2. Supply Chain Security

bash
# View package integrity
npm view <package> integrity

# Check package source
npm view <package> repository

# View package maintainers
npm view <package> maintainers

3. License Issues

bash
# Check licenses
npm install -g license-checker
license-checker

# View specific package license
npm view <package> license

Tools and Plugins

1. npm-check-updates

Check for dependency updates:

bash
# Install
npm install -g npm-check-updates

# Check for updates
ncu

# Update package.json
ncu -u

2. npm-check

Check package status:

bash
# Install
npm install -g npm-check

# Check packages
npm-check

# Interactive update
npm-check -u

3. depcheck

Check for unused dependencies:

bash
# Install
npm install -g depcheck

# Check for unused dependencies
depcheck

# Ignore specific packages
depcheck --ignore-missing=package-name

4. npm-why

Explain installation reason for package:

bash
# Install
npm install -g npm-why

# Query package
npm-why <package>

Troubleshooting Workflow

1. General Troubleshooting Workflow

bash
# 1. Clean cache
npm cache clean --force

# 2. Delete node_modules
rm -rf node_modules

# 3. Delete lock file
rm package-lock.json

# 4. Reinstall
npm install

# 5. If still failing, use verbose logging
npm install --verbose

2. Specific Issue Workflows

Installation Failures

bash
# 1. Check network
ping registry.npmjs.org

# 2. Check proxy
npm config get proxy

# 3. Use mirror
npm config set registry https://registry.npmmirror.com

# 4. Reinstall
npm install

Dependency Conflicts

bash
# 1. View dependency tree
npm ls

# 2. View outdated packages
npm outdated

# 3. Update packages
npm update

# 4. Use overrides
npm config set overrides '{"package": "1.2.3"}'

Script Failures

bash
# 1. View scripts
npm run

# 2. Check syntax
cat package.json | grep scripts

# 3. Run script manually
node /path/to/script.js

# 4. View environment variables
npm run <script> --verbose

Best Practices

1. Regular Diagnostics

bash
# Run weekly
npm doctor
npm audit
npm outdated

2. Save Diagnostic Information

bash
# Save diagnostic results
npm doctor > npm-doctor.log
npm audit > npm-audit.log
npm outdated > npm-outdated.log

3. Use Version Control

bash
# Commit package-lock.json
git add package-lock.json
git commit -m "Update lock file"

# Rollback to previous version
git checkout HEAD~1 package-lock.json

4. Document Issues

Create TROUBLESHOOTING.md in project:

markdown
# Troubleshooting

## Common Issues

### Installation Fails

```bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Dependency Conflicts

bash
npm ls
npm update

shell

Mastering npm diagnostic and debugging tools can significantly improve troubleshooting efficiency and reduce downtime during development.