轉(zhuǎn)發(fā) # TypeScript項目引用(project references)
TypeScript新特性之項目引用(project references)
項目引用是TypeScript 3.0中的一項新功能合住，允許您將TypeScript程序構(gòu)建為更小的部分序调。
通過這樣做芥永，您可以大大縮短構(gòu)建時間弓千，實現(xiàn)組件之間的邏輯分離，并以新的更好的方式組織代碼。
我們還為tsc引入了一種新模式，即--build標志，它與項目引用協(xié)同工作羞延，以實現(xiàn)更快的TypeScript構(gòu)建。
示例項目
讓我們看一個相當(dāng)正常的程序脾还，看看項目引用如何幫助我們更好地組織它伴箩。
想象一下，你有一個項目有兩個模塊鄙漏，轉(zhuǎn)換器和單元嗤谚，以及每個模塊的相應(yīng)測試文件：
/src/converter.ts
/src/units.ts
/test/converter-tests.ts
/test/units-tests.ts
/tsconfig.json
測試文件導(dǎo)入實現(xiàn)文件并進行一些測試：
// converter-tests.ts
import * as converter from "../converter";
assert.areEqual(converter.celsiusToFahrenheit(0), 32);
以前，如果您使用單個tsconfig文件怔蚌，則此結(jié)構(gòu)很難處理：
- 實現(xiàn)文件可以導(dǎo)入測試文件
- 在輸出文件夾名稱中沒有出現(xiàn)src的情況下巩步，無法同時構(gòu)建test和src，這可能是您不想要的
- 僅更改實現(xiàn)文件中的內(nèi)部結(jié)構(gòu)需要再次檢查測試桦踊，即使這不會導(dǎo)致新的錯誤
- 僅更改測試需要再次對實現(xiàn)進行檢查椅野，即使沒有任何改變
您可以使用多個tsconfig文件來解決其中的一些問題，但會出現(xiàn)新的問題：
- 沒有內(nèi)置的最新檢查，因此您最終總是運行兩次tsc
- 兩次調(diào)用tsc會導(dǎo)致更多的啟動時間開銷
- tsc -w無法一次在多個配置文件上運行
項目引用(project references)可以解決所有這些問題等等竟闪。
什么是項目引用(project references)?
tsconfig.json文件有一個新的頂級屬性"references"离福。
它是一個對象數(shù)組，指定要引用的項目：
{
"compilerOptions": {
// The usual
},
"references": [
{ "path": "../src" }
]
}
每個引用的path屬性可以指向包含tsconfig.json文件的目錄炼蛤，也可以指向配置文件本身(可以具有任何名稱)妖爷。
當(dāng)您引用項目時，會發(fā)生新的事情：
- 從引用的項目導(dǎo)入模塊將改為加載其輸出聲明文件（.d.ts）
- 如果引用的項目生成outFile理朋，則輸出文件.d.ts文件的聲明將在此項目中可見
- 如果需要絮识，構(gòu)建模式(下面會提到)將自動構(gòu)建引用的項目
通過分成多個項目，您可以大大提高類型檢查和編譯的速度嗽上，減少使用編輯器時的內(nèi)存使用量次舌，并改進程序邏輯分組的實施。
composite
引用的項目必須啟用新的composite設(shè)置炸裆。
需要此設(shè)置以確保TypeScript可以快速確定在何處查找引用項目的輸出垃它。
啟用composite標志會改變一些事情：
- rootDir設(shè)置（如果未顯式設(shè)置）默認為包含tsconfig文件的目錄
- 所有實現(xiàn)文件必須由include模式匹配或在files數(shù)組中列出鲜屏。如果違反此約束烹看，tsc將通知您未指定哪些文件
- declaration必須打開
declarationMaps
我們還增加了對declaration source maps的支持。如果啟用--declarationMap洛史，您將能夠使用編輯器功能惯殊，如"轉(zhuǎn)到定義"和重命名，以在支持的編輯器中跨項目邊界透明地導(dǎo)航和編輯代碼也殖。
以outFile為前綴
您還可以使用引用中的prepend選項啟用前置依賴項的輸出：
"references": [
{ "path": "../utils", "prepend": true }
]
預(yù)先設(shè)置項目將包括項目的輸出高于當(dāng)前項目的輸出土思。
這適用于.js文件和.d.ts文件，源代碼映射文件也將正確發(fā)出忆嗜。
tsc只會使用磁盤上的現(xiàn)有文件來執(zhí)行此過程己儒，因此可以創(chuàng)建一個項目，其中無法生成正確的輸出文件捆毫，因為某些項目的輸出將在結(jié)果文件中出現(xiàn)多次闪湾。
例如：
A
^ ^
/ \
B C
^ ^
\ /
D
在這種情況下，重要的是不要在每個參考文獻中添加前綴绩卤，因為在D的輸出中最終會得到兩個A副本 - 這可能會導(dǎo)致意外結(jié)果途样。
項目引用的注意事項
項目引用有一些您應(yīng)該注意的權(quán)衡。
因為依賴項目使用從其依賴項構(gòu)建的.d.ts文件濒憋，所以您必須在克隆之后簽入某些構(gòu)建輸出或構(gòu)建項目何暇，然后才能在編輯器中導(dǎo)航項目而不會看到虛假錯誤。
我們正在開發(fā)一個能夠緩解這種情況的幕后.d.ts生成過程凛驮，但是現(xiàn)在我們建議告知開發(fā)人員他們應(yīng)該在克隆之后構(gòu)建它們裆站。
此外，為了保持與現(xiàn)有構(gòu)建工作流的兼容性，除非使用--build開關(guān)調(diào)用遏插，否則tsc不會自動構(gòu)建依賴項捂贿。
讓我們了解更多關(guān)于--build的信息。
TypeScript的構(gòu)建模式
期待已久的功能是TypeScript項目的智能增量構(gòu)建胳嘲。
在3.0中厂僧，您可以將-build標志與tsc一起使用。
這實際上是tsc的新入口點了牛，其行為更像構(gòu)建協(xié)調(diào)器而不是簡單的編譯器颜屠。
運行tsc --build(簡稱tsc -b)將執(zhí)行以下操作：
- 查找所有引用的項目
- 檢測它們是否是最新的
- 按正確的順序構(gòu)建過時的項目
您可以為tsc -b提供多個配置文件路徑(例如tsc -b src test)。
就像tsc -p一樣鹰祸，如果命名為tsconfig.json甫窟，則不需要指定配置文件名本身。
> tsc -b # 在當(dāng)前目錄中構(gòu)建tsconfig.json
> tsc -b src # 構(gòu)建src/tsconfig.json
> tsc -b foo/release.tsconfig.json bar # 構(gòu)建foo/release.tsconfig.json和構(gòu)建bar/tsconfig.json
不要擔(dān)心您在命令行上傳遞的排過序的文件 - 如果需要蛙婴，tsc將重新排序它們粗井，以便始終首先構(gòu)建依賴項。
還有一些特定于tsc -b的標志：
--verbose: 打印詳細日志記錄以解釋正在發(fā)生的事情（可能與任何其他標志組合）
--dry: 顯示將要完成的但實際上不構(gòu)建任何內(nèi)容
--clean: 刪除指定項目的輸出（可以與--dry結(jié)合使用）
--force: 就好像所有項目都已過時一樣
--watch: 監(jiān)視模式（除了--verbose外街图，不得與任何標志組合使用）
注意事項
通常浇衬，除非出現(xiàn)noEmitOnError，否則tsc將在出現(xiàn)語法或類型錯誤時生成輸出（.js和.d.ts）餐济。
在增量構(gòu)建系統(tǒng)中執(zhí)行此操作將非常糟糕 - 如果您的一個過時的依賴項出現(xiàn)新錯誤耘擂，您只能看到它一次，因為后續(xù)構(gòu)建將跳過構(gòu)建現(xiàn)在最新的項目絮姆。
因此醉冤，tsc -b實際上就像為所有項目啟用noEmitOnError一樣。
如果您檢查任何構(gòu)建輸出(.js篙悯，.d.ts蚁阳，.d.ts.map等)，您可能需要在某些源控制操作之后運行--force構(gòu)建鸽照，具體取決于源控制工具是否保留
本地副本和遠程副本之間的時間映射螺捐。
MSBuild
如果您有msbuild項目，則可以通過添加如下代碼到您的proj文件來啟用構(gòu)建模式
<TypeScriptBuildMode>true</TypeScriptBuildMode>
這將啟用自動增量構(gòu)建和清潔移宅。
請注意归粉，與tsconfig.json/-p一樣，不會遵循現(xiàn)有的TypeScript項目屬性 - 應(yīng)使用tsconfig文件管理所有設(shè)置漏峰。
一些團隊已經(jīng)設(shè)置了基于msbuild的工作流糠悼，其中tsconfig文件與他們配對的托管項目具有相同的隱式圖表排序。
如果您的解決方案是這樣的浅乔，您可以繼續(xù)使用msbuild和tsc -p以及項目引用;
這些是完全可互操作的倔喂。
指導(dǎo)(Guidance)
整體結(jié)構(gòu)
使用更多tsconfig.json文件铝条，您通常需要使用配置文件繼承來集中您的常用編譯器選項。
這樣席噩，您可以在一個文件中更改設(shè)置班缰，而不必編輯多個文件。
另一個好的做法是擁有一個"解決方案"tsconfig.json文件悼枢，該文件只引用了所有l(wèi)eaf-node項目埠忘。
這提供了一個簡單的切入點;
例如，在TypeScript repo中馒索，我們只運行tsc -b src來構(gòu)建所有端點莹妒，因為我們列出了src/tsconfig.json中的所有子項目。請注意绰上，從3.0開始旨怠，如果在tsconfig.json中至少有一個reference將不會針對空的files數(shù)組報錯
您可以在TypeScript存儲庫中看到這些模式 - src/tsconfig_base.json，src/tsconfig.json和src/tsc/tsconfig.json作為關(guān)鍵示例蜈块。
構(gòu)建相關(guān)模塊
通常鉴腻，使用相關(guān)模塊transition a repo并不需要太多。
只需將tsconfig.json文件放在給定父文件夾的每個子目錄中百揭，并添加對這些配置文件的引用以匹配程序的預(yù)期分層爽哎。
您需要將outDir設(shè)置為輸出文件夾的顯式子文件夾，或?qū)ootDir設(shè)置為所有項目文件夾的公共根目錄信峻。
構(gòu)建outFiles
使用outFile進行編譯的布局更靈活倦青，因為相對路徑無關(guān)緊要瓮床。
要記住的一件事是盹舞，您通常希望在"最后"項目之前不使用前置 - 這將改善構(gòu)建時間并減少任何給定構(gòu)建中所需的I/O量。
TypeScript repo本身就是一個很好的參考 - 我們有一些"庫"項目和一些"端點"項目;
"端點"項目盡可能小隘庄，只吸引他們需要的庫踢步。
原文地址：
http://www.typescriptlang.org/docs/handbook/project-references.html
