0
# Diagnostics
1

2
Comprehensive project health checking system that validates environment, configuration, packages, and provides recommendations.
3

4
## Capabilities
5

6
### Doctor System
7

8
Main diagnostic system that runs comprehensive health checks on Taro projects.
9

10
```typescript { .api }
11
/**
12
 * Doctor diagnostic system with validation functions
13
 */
14
const doctor: {
15
  /** Array of validation functions for comprehensive project checking */
16
  validators: Array<(args?: any) => Promise<void> | void>;
17
};
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { doctor } from "@tarojs/cli";
24

25
// Access all validators
26
const allValidators = doctor.validators;
27

28
// Run specific validator
29
const envValidator = doctor.validators[0];
30
await envValidator();
31

32
// Run configuration validator
33
const configValidator = doctor.validators[1];
34
await configValidator({
35
  projectConfig: myProjectConfig,
36
  helper: helperUtils
37
});
38
```
39

40
### Validation Functions
41

42
Individual validation functions that check different aspects of the Taro project.
43

44
```typescript { .api }
45
/**
46
 * Environment validation - checks Node.js version, system requirements
47
 * @returns Promise resolving when validation completes
48
 */
49
function validateEnv(): Promise<void>;
50

51
/**
52
 * Configuration validation - validates Taro project configuration
53
 * @param projectConfig - Project configuration object
54
 * @param helper - Helper utilities object
55
 * @returns Promise resolving when validation completes
56
 */
57
function validateConfig(
58
  projectConfig: IProjectConfig,
59
  helper: HelperUtils
60
): Promise<void>;
61

62
/**
63
 * Package validation - checks dependencies and package integrity
64
 * @param appPath - Application root path
65
 * @param nodeModulesPath - Node modules directory path
66
 * @returns Promise resolving when validation completes
67
 */
68
function validatePackage(
69
  appPath: string,
70
  nodeModulesPath: string
71
): Promise<void>;
72

73
/**
74
 * Recommendations validation - provides optimization suggestions
75
 * @param appPath - Application root path
76
 * @returns Promise resolving when validation completes
77
 */
78
function validateRecommend(appPath: string): Promise<void>;
79

80
/**
81
 * ESLint validation - checks linting configuration and rules
82
 * @param projectConfig - Project configuration object
83
 * @param chalk - Chalk utility for colored output
84
 * @returns Promise resolving when validation completes
85
 */
86
function validateEslint(
87
  projectConfig: IProjectConfig,
88
  chalk: ChalkInstance
89
): Promise<void>;
90
```
91

92
### Diagnostic Categories
93

94
Different categories of diagnostics performed by the doctor system.
95

96
```typescript { .api }
97
/**
98
 * Environment diagnostic results
99
 */
100
interface EnvironmentDiagnostic {
101
  nodeVersion: {
102
    current: string;
103
    required: string;
104
    compatible: boolean;
105
  };
106
  npmVersion: {
107
    current: string;
108
    compatible: boolean;
109
  };
110
  operatingSystem: {
111
    platform: string;
112
    arch: string;
113
    supported: boolean;
114
  };
115
  globalPackages: {
116
    taroCliVersion: string;
117
    otherGlobalPackages: string[];
118
  };
119
}
120

121
/**
122
 * Configuration diagnostic results
123
 */
124
interface ConfigurationDiagnostic {
125
  configFile: {
126
    exists: boolean;
127
    path: string;
128
    syntax: 'valid' | 'invalid';
129
  };
130
  projectSettings: {
131
    framework: string;
132
    compiler: string;
133
    outputRoot: string;
134
    sourceRoot: string;
135
  };
136
  pluginConfiguration: {
137
    validPlugins: string[];
138
    invalidPlugins: string[];
139
    missingPlugins: string[];
140
  };
141
}
142

143
/**
144
 * Package diagnostic results
145
 */
146
interface PackageDiagnostic {
147
  dependencies: {
148
    missing: string[];
149
    outdated: Array<{
150
      name: string;
151
      current: string;
152
      latest: string;
153
    }>;
154
    conflicting: Array<{
155
      name: string;
156
      versions: string[];
157
    }>;
158
  };
159
  peerDependencies: {
160
    missing: string[];
161
    incompatible: string[];
162
  };
163
  lockFile: {
164
    exists: boolean;
165
    type: 'package-lock.json' | 'yarn.lock' | 'pnpm-lock.yaml';
166
  };
167
}
168
```
169

170
### Diagnostic Output Format
171

172
Structured output format for diagnostic results with severity levels and recommendations.
173

174
```typescript { .api }
175
/**
176
 * Diagnostic result severity levels
177
 */
178
type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'success';
179

180
/**
181
 * Individual diagnostic result
182
 */
183
interface DiagnosticResult {
184
  /** Diagnostic category */
185
  category: 'environment' | 'configuration' | 'packages' | 'recommendations' | 'eslint';
186
  /** Result severity */
187
  severity: DiagnosticSeverity;
188
  /** Diagnostic message */
189
  message: string;
190
  /** Detailed description */
191
  description?: string;
192
  /** Suggested fix or action */
193
  fix?: string;
194
  /** Commands to resolve the issue */
195
  commands?: string[];
196
  /** Related documentation links */
197
  docs?: string[];
198
}
199

200
/**
201
 * Complete diagnostic report
202
 */
203
interface DiagnosticReport {
204
  /** Overall health status */
205
  status: 'healthy' | 'warnings' | 'errors';
206
  /** Individual diagnostic results */
207
  results: DiagnosticResult[];
208
  /** Summary statistics */
209
  summary: {
210
    total: number;
211
    errors: number;
212
    warnings: number;
213
    info: number;
214
    success: number;
215
  };
216
  /** Execution timestamp */
217
  timestamp: string;
218
  /** Environment context */
219
  environment: {
220
    nodeVersion: string;
221
    taroVersion: string;
222
    platform: string;
223
  };
224
}
225
```
226

227
### Common Diagnostic Issues
228

229
Frequently encountered issues and their diagnostic patterns.
230

231
```typescript { .api }
232
/**
233
 * Common environment issues detected by diagnostics
234
 */
235
interface CommonEnvironmentIssues {
236
  'node-version-outdated': {
237
    severity: 'error';
238
    message: 'Node.js version is outdated';
239
    fix: 'Update Node.js to version 18 or higher';
240
    commands: ['nvm install 18', 'nvm use 18'];
241
  };
242
  'missing-global-cli': {
243
    severity: 'warning';
244
    message: 'Taro CLI not installed globally';
245
    fix: 'Install Taro CLI globally';
246
    commands: ['npm install -g @tarojs/cli'];
247
  };
248
  'incompatible-npm': {
249
    severity: 'warning';
250
    message: 'npm version may cause issues';
251
    fix: 'Update npm to latest version';
252
    commands: ['npm install -g npm@latest'];
253
  };
254
}
255

256
/**
257
 * Common configuration issues
258
 */
259
interface CommonConfigurationIssues {
260
  'missing-config-file': {
261
    severity: 'error';
262
    message: 'Taro configuration file not found';
263
    fix: 'Create config/index.js file';
264
  };
265
  'invalid-framework': {
266
    severity: 'error';
267
    message: 'Unsupported framework specified';
268
    fix: 'Use supported framework: react, vue3, preact, or solid';
269
  };
270
  'missing-platform-plugin': {
271
    severity: 'error';
272
    message: 'Platform plugin not found';
273
    fix: 'Install required platform plugin';
274
  };
275
}
276

277
/**
278
 * Common package issues
279
 */
280
interface CommonPackageIssues {
281
  'peer-dependency-missing': {
282
    severity: 'error';
283
    message: 'Required peer dependency is missing';
284
    fix: 'Install missing peer dependencies';
285
  };
286
  'version-conflict': {
287
    severity: 'warning';
288
    message: 'Package version conflicts detected';
289
    fix: 'Resolve version conflicts in dependencies';
290
  };
291
  'outdated-dependencies': {
292
    severity: 'info';
293
    message: 'Some dependencies are outdated';
294
    fix: 'Update dependencies to latest versions';
295
  };
296
}
297
```
298

299
### Diagnostic Utilities
300

301
Helper functions for running diagnostics and formatting output.
302

303
```typescript { .api }
304
/**
305
 * Run all diagnostic checks
306
 * @param projectPath - Path to Taro project
307
 * @returns Complete diagnostic report
308
 */
309
function runDiagnostics(projectPath: string): Promise<DiagnosticReport>;
310

311
/**
312
 * Run specific diagnostic category
313
 * @param category - Diagnostic category to run
314
 * @param projectPath - Path to Taro project
315
 * @returns Filtered diagnostic results
316
 */
317
function runSpecificDiagnostic(
318
  category: DiagnosticResult['category'],
319
  projectPath: string
320
): Promise<DiagnosticResult[]>;
321

322
/**
323
 * Format diagnostic results for console output
324
 * @param report - Diagnostic report to format
325
 * @returns Formatted string for console display
326
 */
327
function formatDiagnosticOutput(report: DiagnosticReport): string;
328

329
/**
330
 * Export diagnostic results to file
331
 * @param report - Diagnostic report to export
332
 * @param outputPath - File path for export
333
 * @param format - Export format
334
 */
335
function exportDiagnostics(
336
  report: DiagnosticReport,
337
  outputPath: string,
338
  format: 'json' | 'html' | 'markdown'
339
): Promise<void>;
340
```
341

342
### Diagnostic Configuration
343

344
Configuration options for customizing diagnostic behavior.
345

346
```typescript { .api }
347
/**
348
 * Diagnostic configuration options
349
 */
350
interface DiagnosticConfig {
351
  /** Enable or disable specific diagnostic categories */
352
  categories?: {
353
    environment?: boolean;
354
    configuration?: boolean;
355
    packages?: boolean;
356
    recommendations?: boolean;
357
    eslint?: boolean;
358
  };
359
  /** Severity threshold for reporting */
360
  severityThreshold?: DiagnosticSeverity;
361
  /** Output format preferences */
362
  output?: {
363
    format: 'console' | 'json' | 'html';
364
    verbose?: boolean;
365
    colors?: boolean;
366
  };
367
  /** Include or exclude specific checks */
368
  checks?: {
369
    include?: string[];
370
    exclude?: string[];
371
  };
372
}
373

374
/**
375
 * Apply diagnostic configuration
376
 * @param config - Configuration options
377
 */
378
function configureDiagnostics(config: DiagnosticConfig): void;
379
```
380

381
**Command Line Usage:**
382

383
```bash
384
# Run all diagnostics
385
taro doctor
386

387
# Run with verbose output
388
taro doctor --verbose
389

390
# Export results to file
391
taro doctor --output report.json
392

393
# Run specific category only
394
taro doctor --category environment
395

396
# Skip specific checks
397
taro doctor --exclude eslint,packages
398
```