@weapp-tailwindcss/cli 5.4.1 → 5.5.0

package/README.md

@@ -53,6 +53,8 @@ const exitCode = await runCli(['-i', 'src/input.css', '-o', 'dist/output.css'])
 
 Importing the package does not execute the CLI. `runCli` follows the same stdout, stderr, and `process.exitCode` behavior as the binary.
 
+Use `weapp-tw doctor` when integrating or upgrading a project. It only reports duplicate Tailwind generation when a configuration actually references `@tailwindcss/vite` or `@tailwindcss/postcss`; a plain PostCSS config is not treated as an error.
+
 ## Documentation
 
 See the [CLI guide](https://tw.weapp.dev/docs/tools/weapp-tw-cli) for all options, stdin/stdout, source maps, watch mode, and `canonicalize`.

package/README.zh-CN.md

@@ -56,3 +56,5 @@ const exitCode = await runCli(['-i', 'src/input.css', '-o', 'dist/output.css'])
 ## 文档
 
 完整参数、stdin/stdout、source map、watch 与 `canonicalize` 用法见 [CLI 使用指南](https://tw.weapp.dev/zh-cn/docs/tools/weapp-tw-cli)。
+
+接入或升级排障时，可以运行 `weapp-tw doctor`。它会检查实际配置中是否注册了官方 Tailwind 生成器；仅存在普通 PostCSS 配置不会触发重复生成警告。

package/dist/bin.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_src = require("./src-CrXWQNny.cjs");
+const require_src = require("./src-C4Y7BTX1.cjs");
 let node_process = require("node:process");
 node_process = require_src.__toESM(node_process, 1);
 //#region src/bin.ts

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as runCli } from "./src-BfHGXT3j.js";
+import { t as runCli } from "./src-Dpl0bugL.js";
 import process from "node:process";
 //#region src/bin.ts
 process.title = "node (@weapp-tailwindcss/cli)";

package/dist/index.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-CrXWQNny.cjs");
+const require_src = require("./src-C4Y7BTX1.cjs");
 exports.runCli = require_src.runCli;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { t as runCli } from "./src-BfHGXT3j.js";
+import { t as runCli } from "./src-Dpl0bugL.js";
 export { runCli };

package/dist/{src-CrXWQNny.cjs → src-C4Y7BTX1.cjs}

@@ -475,7 +475,7 @@ async function runTailwindCli(rawArgv) {
 }
 //#endregion
 //#region package.json
-var version = "5.4.1";
+var version = "5.5.0";
 //#endregion
 //#region src/constants.ts
 const WEAPP_TW_REQUIRED_NODE_VERSION_RANGE = "^22.18.0 || >=24.11.0";
@@ -522,6 +522,90 @@ const FRAMEWORK_DEPS = [
 	["remax", "Remax"]
 ];
 //#endregion
+//#region src/doctor/semantics.ts
+function readConfigText(cwd, file) {
+	if (!file) return;
+	try {
+		return (0, node_fs.readFileSync)(node_path.default.join(cwd, file), "utf8");
+	} catch {
+		return;
+	}
+}
+function stripConfigComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/(?<!:)\/\/.*$/gmu, "");
+}
+function findConfiguredTailwindOwners(cwd, files) {
+	const owners = /* @__PURE__ */ new Set();
+	const evidence = [];
+	for (const file of files) {
+		const source = readConfigText(cwd, file);
+		if (!source) continue;
+		const config = stripConfigComments(source);
+		if (/['"]@tailwindcss\/vite['"]/u.test(config)) {
+			owners.add("vite");
+			evidence.push(file);
+		}
+		if (/['"]@tailwindcss\/postcss['"]/u.test(config)) {
+			owners.add("postcss");
+			evidence.push(file);
+		}
+	}
+	return {
+		owners,
+		evidence: [...new Set(evidence)]
+	};
+}
+function extractConfiguredCssEntries(source) {
+	if (!source) return [];
+	const match = stripConfigComments(source).match(/cssEntries\s*:\s*\[([\s\S]*?)\]/u);
+	if (!match?.[1]) return [];
+	return [...match[1].matchAll(/["']([^"']+\.css)["']/gu)].map((item) => item[1]).filter(Boolean);
+}
+function extractConfiguredOption(source, option) {
+	if (!source) return;
+	return stripConfigComments(source).match(new RegExp(`\\b${option}\\s*:\\s*["']([^"']+)["']`, "u"))?.[1];
+}
+function extractGeneratorTarget(source) {
+	if (!source) return;
+	const config = stripConfigComments(source);
+	const generator = config.match(/generator\s*:\s*\{([\s\S]*?)\}/u)?.[1];
+	return extractConfiguredOption(generator, "target") ?? extractConfiguredOption(config, "target");
+}
+function extractCssSources(source) {
+	const directives = [];
+	for (const match of source.matchAll(/@source\s+(?:(not)\s+)?(?:(inline)\s*\(\s*)?["']([^"']*)["']/gu)) {
+		const value = match[3]?.trim();
+		if (value) directives.push({
+			value,
+			excluded: Boolean(match[1]),
+			inline: Boolean(match[2])
+		});
+	}
+	return directives;
+}
+function resolveSourceProbePath(cssFile, source) {
+	const wildcard = source.search(/[!*?[{]/u);
+	const prefix = wildcard >= 0 ? source.slice(0, wildcard) : source;
+	const directory = wildcard >= 0 ? node_path.default.dirname(prefix) : prefix;
+	return node_path.default.resolve(node_path.default.dirname(cssFile), directory || ".");
+}
+const SUPPORTED_APP_TYPES = /* @__PURE__ */ new Set([
+	"uni-app",
+	"uni-app-vite",
+	"uni-app-x",
+	"taro",
+	"remax",
+	"native",
+	"kbone",
+	"mpx",
+	"weapp-vite"
+]);
+const SUPPORTED_GENERATOR_TARGETS = /* @__PURE__ */ new Set([
+	"web",
+	"weapp",
+	"app"
+]);
+//#endregion
 //#region src/doctor.ts
 function tryReadJson(file) {
 	try {
@@ -561,7 +645,11 @@ function detectFrameworks(deps) {
 	return FRAMEWORK_DEPS.filter(([dependency]) => dependency in deps).map(([, label]) => label);
 }
 function addCheck(checks, check) {
-	checks.push(check);
+	checks.push({
+		...check,
+		code: check.code ?? check.id,
+		evidence: check.evidence ?? []
+	});
 }
 function summarizeChecks(checks) {
 	return checks.reduce((summary, check) => {
@@ -593,13 +681,37 @@ function createDoctorReport(options = {}) {
 	const checks = [];
 	const packageManager = detectPackageManager(cwd, pkg);
 	const frameworks = detectFrameworks(deps);
-	const tailwindcssVersion = readDependencyVersion(cwd, "tailwindcss");
-	const weappTailwindcssVersion = readDependencyVersion(cwd, "weapp-tailwindcss");
+	const tailwindcssVersion = hasDependency(deps, "tailwindcss") ? readDependencyVersion(cwd, "tailwindcss") : void 0;
+	const weappTailwindcssVersion = hasDependency(deps, "weapp-tailwindcss") ? readDependencyVersion(cwd, "weapp-tailwindcss") : void 0;
 	const tailwindMajor = getMajorVersion(tailwindcssVersion) ?? getDependencyMajor(deps, "tailwindcss");
 	const tailwindConfig = findFirstExisting(cwd, CONFIG_FILES.tailwind);
 	const postcssConfig = findFirstExisting(cwd, CONFIG_FILES.postcss);
 	const viteConfig = findFirstExisting(cwd, CONFIG_FILES.vite);
 	const webpackConfig = findFirstExisting(cwd, CONFIG_FILES.webpack);
+	const tailwindOwners = findConfiguredTailwindOwners(cwd, [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	]);
+	const cssEntries = [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	].map((file) => ({
+		file,
+		source: readConfigText(cwd, file)
+	})).flatMap(({ file, source }) => extractConfiguredCssEntries(source).map((entry) => ({
+		file,
+		entry
+	})));
+	const buildConfigs = [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	].map((file) => ({
+		file,
+		source: readConfigText(cwd, file)
+	})).filter((item) => Boolean(item.file && item.source));
 	addCheck(checks, pkg ? {
 		id: "package-json",
 		title: "package.json",
@@ -683,13 +795,112 @@ function createDoctorReport(options = {}) {
 		message: "未检测到 postcss.config.*。",
 		suggestion: "如果通过 PostCSS 接入，请补充 postcss.config.*；如果通过 Vite/Taro 插件接入，可忽略此项。"
 	});
-	if (tailwindMajor === 4 && postcssConfig && !hasDependency(deps, "@tailwindcss/postcss")) addCheck(checks, {
-		id: "tailwindcss-v4-postcss",
-		title: "Tailwind v4 PostCSS",
+	if (tailwindMajor === 4 && tailwindOwners.owners.size > 0) addCheck(checks, {
+		id: "tailwindcss-generator-owner",
+		title: "Tailwind 生成器归属",
 		status: "warn",
-		message: "Tailwind CSS v4 项目存在 PostCSS 配置，但未检测到 @tailwindcss/postcss。",
-		suggestion: "如果 PostCSS 配置中仍直接使用 tailwindcss，请迁移到 @tailwindcss/postcss。"
+		message: `检测到官方 Tailwind ${[...tailwindOwners.owners].join(" 与 ")} 生成器配置。生成模式下不要与 WeappTailwindcss 同时运行两套 Tailwind 生成器。`,
+		suggestion: "移除 @tailwindcss/vite 或 @tailwindcss/postcss 的生成配置，仅保留 WeappTailwindcss；PostCSS 中可以继续保留其他业务插件。",
+		code: "duplicate-tailwind-generator",
+		evidence: tailwindOwners.evidence
 	});
+	if (tailwindMajor === 4 && cssEntries.length > 0) {
+		const missingEntries = cssEntries.filter(({ entry }) => !(0, node_fs.existsSync)(node_path.default.resolve(cwd, entry)));
+		const entriesWithoutTailwindImport = cssEntries.filter(({ entry }) => {
+			if (!(0, node_fs.existsSync)(node_path.default.resolve(cwd, entry))) return false;
+			try {
+				const source = (0, node_fs.readFileSync)(node_path.default.resolve(cwd, entry), "utf8");
+				return !/@import\s+["']tailwindcss["']/u.test(source) && !/@import\s+["']tailwindcss\//u.test(source);
+			} catch {
+				return false;
+			}
+		});
+		if (missingEntries.length > 0) addCheck(checks, {
+			id: "tailwind-css-entry",
+			title: "Tailwind CSS 入口",
+			status: "error",
+			message: `配置了不存在的 cssEntries：${missingEntries.map((item) => item.entry).join(", ")}。`,
+			suggestion: "请将 cssEntries 改为项目根目录解析出的绝对路径，或确认入口文件已创建。",
+			code: "missing-css-entry",
+			evidence: missingEntries.map((item) => item.file).filter((file) => Boolean(file))
+		});
+		if (entriesWithoutTailwindImport.length > 0) addCheck(checks, {
+			id: "tailwind-css-entry-import",
+			title: "Tailwind CSS 入口内容",
+			status: "warn",
+			message: `cssEntries 指向的文件未发现 @import "tailwindcss"：${entriesWithoutTailwindImport.map((item) => item.entry).join(", ")}。`,
+			suggestion: "请在纯 CSS 入口中加入 @import \"tailwindcss\"，并确保该文件被应用构建图实际引入。",
+			code: "missing-tailwind-import",
+			evidence: entriesWithoutTailwindImport.map((item) => node_path.default.resolve(cwd, item.entry))
+		});
+		cssEntries.flatMap(({ entry }) => {
+			const cssFile = node_path.default.resolve(cwd, entry);
+			if (!(0, node_fs.existsSync)(cssFile)) return [];
+			let source;
+			try {
+				source = (0, node_fs.readFileSync)(cssFile, "utf8");
+			} catch {
+				return [];
+			}
+			const directives = extractCssSources(source);
+			const diagnostics = [];
+			if (!directives.some((directive) => !directive.excluded)) diagnostics.push({
+				id: "tailwind-css-source",
+				title: "Tailwind CSS 来源范围",
+				status: "warn",
+				message: `${entry} 未发现 @source，Tailwind 可能无法扫描项目源码。`,
+				suggestion: "请在 CSS 入口中加入覆盖实际源码目录的 @source；仅配置 cssEntries 不会替代源码扫描声明。",
+				code: "missing-tailwind-source",
+				evidence: [cssFile]
+			});
+			for (const directive of directives) {
+				if (directive.inline || directive.excluded) continue;
+				const probePath = resolveSourceProbePath(cssFile, directive.value);
+				if (!(0, node_fs.existsSync)(probePath)) diagnostics.push({
+					id: "tailwind-css-source-path",
+					title: "Tailwind @source 路径",
+					status: "warn",
+					message: `@source ${directive.value} 的路径不存在或无法从入口解析。`,
+					suggestion: "请按 CSS 入口所在目录修正 @source 相对路径，或确认源码目录已经创建。",
+					code: "invalid-tailwind-source",
+					evidence: [cssFile, probePath]
+				});
+			}
+			return diagnostics;
+		}).forEach((check) => addCheck(checks, check));
+	}
+	for (const { file, source } of buildConfigs) {
+		const appType = extractConfiguredOption(source, "appType");
+		if (appType && !SUPPORTED_APP_TYPES.has(appType)) addCheck(checks, {
+			id: "app-type",
+			title: "appType 配置",
+			status: "error",
+			message: `${file} 使用了不受支持的 appType：${appType}。`,
+			suggestion: "请改为 uni-app、uni-app-x、taro、mpx、weapp-vite 或其他公开支持的 appType。",
+			code: "invalid-app-type",
+			evidence: [file]
+		});
+		const target = extractGeneratorTarget(source);
+		if (target && !SUPPORTED_GENERATOR_TARGETS.has(target)) addCheck(checks, {
+			id: "generator-target",
+			title: "生成目标",
+			status: "error",
+			message: `${file} 使用了不受支持的 generator.target：${target}。`,
+			suggestion: "请使用 web、weapp 或 app；普通 Vite Web 项目推荐使用 web。",
+			code: "invalid-generator-target",
+			evidence: [file]
+		});
+		const platform = extractConfiguredOption(source, "platform");
+		if (platform && target && (platform === "web" && target !== "web" || platform !== "web" && target === "web")) addCheck(checks, {
+			id: "generator-platform",
+			title: "生成目标与平台",
+			status: "warn",
+			message: `${file} 的 platform=${platform} 与 generator.target=${target} 可能不一致。`,
+			suggestion: "请让 platform 与 generator.target 指向同一运行端，或删除不必要的显式覆盖以使用自动推断。",
+			code: "generator-target-platform-conflict",
+			evidence: [file]
+		});
+	}
 	addCheck(checks, frameworks.length > 0 ? {
 		id: "framework",
 		title: "框架识别",

package/dist/{src-BfHGXT3j.js → src-Dpl0bugL.js}

@@ -446,7 +446,7 @@ async function runTailwindCli(rawArgv) {
 }
 //#endregion
 //#region package.json
-var version = "5.4.1";
+var version = "5.5.0";
 //#endregion
 //#region src/constants.ts
 const WEAPP_TW_REQUIRED_NODE_VERSION_RANGE = "^22.18.0 || >=24.11.0";
@@ -493,6 +493,90 @@ const FRAMEWORK_DEPS = [
 	["remax", "Remax"]
 ];
 //#endregion
+//#region src/doctor/semantics.ts
+function readConfigText(cwd, file) {
+	if (!file) return;
+	try {
+		return readFileSync(path.join(cwd, file), "utf8");
+	} catch {
+		return;
+	}
+}
+function stripConfigComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/(?<!:)\/\/.*$/gmu, "");
+}
+function findConfiguredTailwindOwners(cwd, files) {
+	const owners = /* @__PURE__ */ new Set();
+	const evidence = [];
+	for (const file of files) {
+		const source = readConfigText(cwd, file);
+		if (!source) continue;
+		const config = stripConfigComments(source);
+		if (/['"]@tailwindcss\/vite['"]/u.test(config)) {
+			owners.add("vite");
+			evidence.push(file);
+		}
+		if (/['"]@tailwindcss\/postcss['"]/u.test(config)) {
+			owners.add("postcss");
+			evidence.push(file);
+		}
+	}
+	return {
+		owners,
+		evidence: [...new Set(evidence)]
+	};
+}
+function extractConfiguredCssEntries(source) {
+	if (!source) return [];
+	const match = stripConfigComments(source).match(/cssEntries\s*:\s*\[([\s\S]*?)\]/u);
+	if (!match?.[1]) return [];
+	return [...match[1].matchAll(/["']([^"']+\.css)["']/gu)].map((item) => item[1]).filter(Boolean);
+}
+function extractConfiguredOption(source, option) {
+	if (!source) return;
+	return stripConfigComments(source).match(new RegExp(`\\b${option}\\s*:\\s*["']([^"']+)["']`, "u"))?.[1];
+}
+function extractGeneratorTarget(source) {
+	if (!source) return;
+	const config = stripConfigComments(source);
+	const generator = config.match(/generator\s*:\s*\{([\s\S]*?)\}/u)?.[1];
+	return extractConfiguredOption(generator, "target") ?? extractConfiguredOption(config, "target");
+}
+function extractCssSources(source) {
+	const directives = [];
+	for (const match of source.matchAll(/@source\s+(?:(not)\s+)?(?:(inline)\s*\(\s*)?["']([^"']*)["']/gu)) {
+		const value = match[3]?.trim();
+		if (value) directives.push({
+			value,
+			excluded: Boolean(match[1]),
+			inline: Boolean(match[2])
+		});
+	}
+	return directives;
+}
+function resolveSourceProbePath(cssFile, source) {
+	const wildcard = source.search(/[!*?[{]/u);
+	const prefix = wildcard >= 0 ? source.slice(0, wildcard) : source;
+	const directory = wildcard >= 0 ? path.dirname(prefix) : prefix;
+	return path.resolve(path.dirname(cssFile), directory || ".");
+}
+const SUPPORTED_APP_TYPES = /* @__PURE__ */ new Set([
+	"uni-app",
+	"uni-app-vite",
+	"uni-app-x",
+	"taro",
+	"remax",
+	"native",
+	"kbone",
+	"mpx",
+	"weapp-vite"
+]);
+const SUPPORTED_GENERATOR_TARGETS = /* @__PURE__ */ new Set([
+	"web",
+	"weapp",
+	"app"
+]);
+//#endregion
 //#region src/doctor.ts
 function tryReadJson(file) {
 	try {
@@ -532,7 +616,11 @@ function detectFrameworks(deps) {
 	return FRAMEWORK_DEPS.filter(([dependency]) => dependency in deps).map(([, label]) => label);
 }
 function addCheck(checks, check) {
-	checks.push(check);
+	checks.push({
+		...check,
+		code: check.code ?? check.id,
+		evidence: check.evidence ?? []
+	});
 }
 function summarizeChecks(checks) {
 	return checks.reduce((summary, check) => {
@@ -564,13 +652,37 @@ function createDoctorReport(options = {}) {
 	const checks = [];
 	const packageManager = detectPackageManager(cwd, pkg);
 	const frameworks = detectFrameworks(deps);
-	const tailwindcssVersion = readDependencyVersion(cwd, "tailwindcss");
-	const weappTailwindcssVersion = readDependencyVersion(cwd, "weapp-tailwindcss");
+	const tailwindcssVersion = hasDependency(deps, "tailwindcss") ? readDependencyVersion(cwd, "tailwindcss") : void 0;
+	const weappTailwindcssVersion = hasDependency(deps, "weapp-tailwindcss") ? readDependencyVersion(cwd, "weapp-tailwindcss") : void 0;
 	const tailwindMajor = getMajorVersion(tailwindcssVersion) ?? getDependencyMajor(deps, "tailwindcss");
 	const tailwindConfig = findFirstExisting(cwd, CONFIG_FILES.tailwind);
 	const postcssConfig = findFirstExisting(cwd, CONFIG_FILES.postcss);
 	const viteConfig = findFirstExisting(cwd, CONFIG_FILES.vite);
 	const webpackConfig = findFirstExisting(cwd, CONFIG_FILES.webpack);
+	const tailwindOwners = findConfiguredTailwindOwners(cwd, [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	]);
+	const cssEntries = [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	].map((file) => ({
+		file,
+		source: readConfigText(cwd, file)
+	})).flatMap(({ file, source }) => extractConfiguredCssEntries(source).map((entry) => ({
+		file,
+		entry
+	})));
+	const buildConfigs = [
+		postcssConfig,
+		viteConfig,
+		webpackConfig
+	].map((file) => ({
+		file,
+		source: readConfigText(cwd, file)
+	})).filter((item) => Boolean(item.file && item.source));
 	addCheck(checks, pkg ? {
 		id: "package-json",
 		title: "package.json",
@@ -654,13 +766,112 @@ function createDoctorReport(options = {}) {
 		message: "未检测到 postcss.config.*。",
 		suggestion: "如果通过 PostCSS 接入，请补充 postcss.config.*；如果通过 Vite/Taro 插件接入，可忽略此项。"
 	});
-	if (tailwindMajor === 4 && postcssConfig && !hasDependency(deps, "@tailwindcss/postcss")) addCheck(checks, {
-		id: "tailwindcss-v4-postcss",
-		title: "Tailwind v4 PostCSS",
+	if (tailwindMajor === 4 && tailwindOwners.owners.size > 0) addCheck(checks, {
+		id: "tailwindcss-generator-owner",
+		title: "Tailwind 生成器归属",
 		status: "warn",
-		message: "Tailwind CSS v4 项目存在 PostCSS 配置，但未检测到 @tailwindcss/postcss。",
-		suggestion: "如果 PostCSS 配置中仍直接使用 tailwindcss，请迁移到 @tailwindcss/postcss。"
+		message: `检测到官方 Tailwind ${[...tailwindOwners.owners].join(" 与 ")} 生成器配置。生成模式下不要与 WeappTailwindcss 同时运行两套 Tailwind 生成器。`,
+		suggestion: "移除 @tailwindcss/vite 或 @tailwindcss/postcss 的生成配置，仅保留 WeappTailwindcss；PostCSS 中可以继续保留其他业务插件。",
+		code: "duplicate-tailwind-generator",
+		evidence: tailwindOwners.evidence
 	});
+	if (tailwindMajor === 4 && cssEntries.length > 0) {
+		const missingEntries = cssEntries.filter(({ entry }) => !existsSync(path.resolve(cwd, entry)));
+		const entriesWithoutTailwindImport = cssEntries.filter(({ entry }) => {
+			if (!existsSync(path.resolve(cwd, entry))) return false;
+			try {
+				const source = readFileSync(path.resolve(cwd, entry), "utf8");
+				return !/@import\s+["']tailwindcss["']/u.test(source) && !/@import\s+["']tailwindcss\//u.test(source);
+			} catch {
+				return false;
+			}
+		});
+		if (missingEntries.length > 0) addCheck(checks, {
+			id: "tailwind-css-entry",
+			title: "Tailwind CSS 入口",
+			status: "error",
+			message: `配置了不存在的 cssEntries：${missingEntries.map((item) => item.entry).join(", ")}。`,
+			suggestion: "请将 cssEntries 改为项目根目录解析出的绝对路径，或确认入口文件已创建。",
+			code: "missing-css-entry",
+			evidence: missingEntries.map((item) => item.file).filter((file) => Boolean(file))
+		});
+		if (entriesWithoutTailwindImport.length > 0) addCheck(checks, {
+			id: "tailwind-css-entry-import",
+			title: "Tailwind CSS 入口内容",
+			status: "warn",
+			message: `cssEntries 指向的文件未发现 @import "tailwindcss"：${entriesWithoutTailwindImport.map((item) => item.entry).join(", ")}。`,
+			suggestion: "请在纯 CSS 入口中加入 @import \"tailwindcss\"，并确保该文件被应用构建图实际引入。",
+			code: "missing-tailwind-import",
+			evidence: entriesWithoutTailwindImport.map((item) => path.resolve(cwd, item.entry))
+		});
+		cssEntries.flatMap(({ entry }) => {
+			const cssFile = path.resolve(cwd, entry);
+			if (!existsSync(cssFile)) return [];
+			let source;
+			try {
+				source = readFileSync(cssFile, "utf8");
+			} catch {
+				return [];
+			}
+			const directives = extractCssSources(source);
+			const diagnostics = [];
+			if (!directives.some((directive) => !directive.excluded)) diagnostics.push({
+				id: "tailwind-css-source",
+				title: "Tailwind CSS 来源范围",
+				status: "warn",
+				message: `${entry} 未发现 @source，Tailwind 可能无法扫描项目源码。`,
+				suggestion: "请在 CSS 入口中加入覆盖实际源码目录的 @source；仅配置 cssEntries 不会替代源码扫描声明。",
+				code: "missing-tailwind-source",
+				evidence: [cssFile]
+			});
+			for (const directive of directives) {
+				if (directive.inline || directive.excluded) continue;
+				const probePath = resolveSourceProbePath(cssFile, directive.value);
+				if (!existsSync(probePath)) diagnostics.push({
+					id: "tailwind-css-source-path",
+					title: "Tailwind @source 路径",
+					status: "warn",
+					message: `@source ${directive.value} 的路径不存在或无法从入口解析。`,
+					suggestion: "请按 CSS 入口所在目录修正 @source 相对路径，或确认源码目录已经创建。",
+					code: "invalid-tailwind-source",
+					evidence: [cssFile, probePath]
+				});
+			}
+			return diagnostics;
+		}).forEach((check) => addCheck(checks, check));
+	}
+	for (const { file, source } of buildConfigs) {
+		const appType = extractConfiguredOption(source, "appType");
+		if (appType && !SUPPORTED_APP_TYPES.has(appType)) addCheck(checks, {
+			id: "app-type",
+			title: "appType 配置",
+			status: "error",
+			message: `${file} 使用了不受支持的 appType：${appType}。`,
+			suggestion: "请改为 uni-app、uni-app-x、taro、mpx、weapp-vite 或其他公开支持的 appType。",
+			code: "invalid-app-type",
+			evidence: [file]
+		});
+		const target = extractGeneratorTarget(source);
+		if (target && !SUPPORTED_GENERATOR_TARGETS.has(target)) addCheck(checks, {
+			id: "generator-target",
+			title: "生成目标",
+			status: "error",
+			message: `${file} 使用了不受支持的 generator.target：${target}。`,
+			suggestion: "请使用 web、weapp 或 app；普通 Vite Web 项目推荐使用 web。",
+			code: "invalid-generator-target",
+			evidence: [file]
+		});
+		const platform = extractConfiguredOption(source, "platform");
+		if (platform && target && (platform === "web" && target !== "web" || platform !== "web" && target === "web")) addCheck(checks, {
+			id: "generator-platform",
+			title: "生成目标与平台",
+			status: "warn",
+			message: `${file} 的 platform=${platform} 与 generator.target=${target} 可能不一致。`,
+			suggestion: "请让 platform 与 generator.target 指向同一运行端，或删除不必要的显式覆盖以使用自动推断。",
+			code: "generator-target-platform-conflict",
+			evidence: [file]
+		});
+	}
 	addCheck(checks, frameworks.length > 0 ? {
 		id: "framework",
 		title: "框架识别",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weapp-tailwindcss/cli",
   "type": "module",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "description": "Cross-platform Tailwind CSS CLI for Web and mini-program builds. 面向 Web 与小程序构建的跨端 Tailwind CSS CLI。",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "fast-glob": "^3.3.3",
     "lightningcss": "^1.33.0",
     "semver": "~7.8.5",
-    "weapp-tailwindcss": "5.4.1"
+    "weapp-tailwindcss": "5.5.0"
   },
   "scripts": {
     "build": "tsdown",