AIclinicalresearch/docs/09-架构实施/编码规范-UTF8最佳实践.md

# UTF-8 缂栫爜鏈€浣冲疄璺典笌涓<E7AC8C>枃涔辩爜闃茶寖鎸囧崡

## 馃搶 鑳屾櫙

鍦ㄤ换鍔?9锛堝悗绔<E68297>唬鐮佸垎灞傦級鎵ц<E98EB5>杩囩▼涓<E296BC>紝鐢变簬 PowerShell 鎵归噺鎿嶄綔瀵艰嚧浜嗕腑鏂囩紪鐮侀棶棰橈紝寮曞彂浜嗗<E6B59C>涓<EFBFBD>枃浠剁殑瀛楃<E7809B>涓叉湭闂<E6B9AD>悎銆佹敞閲婁唬鐮佸悎骞剁瓑涓ラ噸閿欒<E996BF>锛屽<E9949B>鑷存湇鍔″櫒鏃犳硶鍚<E7A1B6>姩銆?

## 馃攳 涔辩爜浜х敓鐨勬牴鏈<E789B4>師鍥?

### 1. PowerShell 鎵归噺鎿嶄綔鐨勯櫡闃?

```powershell
# 鉂?閿欒<E996BF>绀轰緥锛堜細瀵艰嚧涔辩爜锛?
Get-Content file.ts -Raw -Encoding UTF8 | 
    Set-Content file.ts -NoNewline -Encoding UTF8
```

**闂<><E99782>锛?*
- `-NoNewline` 浼氬<E6B5BC>鑷磋<E991B7>鍚堝苟
- Windows PowerShell 鐨?UTF-8 澶勭悊涓嶅畬鍠?
- 鍙<>兘寮曞叆鎴栫Щ闄?BOM (Byte Order Mark)

### 2. 缂栫爜涓嶄竴鑷?

- UTF-8 with BOM vs UTF-8 without BOM
- Windows (CRLF) vs Unix (LF) 琛屽熬绗?
- 涓嶅悓缂栬緫鍣ㄧ殑榛樿<E6A69B>缂栫爜璁剧疆

## 鉁?瑙ｅ喅鏂规<E98F82>

### 鏂规<E98F82>涓€锛氶」鐩<E3808D>厤缃<E58EA4>枃浠?

#### 1. `.editorconfig`锛堝凡鍒涘缓锛?

纭<EFBFBD>繚鎵€鏈夌紪杈戝櫒缁熶竴浣跨敤锛?
- 缂栫爜锛歎TF-8 without BOM
- 琛屽熬绗︼細LF
- 缂╄繘锛?绌烘牸

#### 2. `.gitattributes`锛堝凡鍒涘缓锛?

闃叉<EFBFBD> Git 鑷<>姩杞<E5A7A9>崲琛屽熬绗﹀<E7BB97>鑷寸殑闂<E6AE91><E99782>銆?

### 鏂规<E98F82>浜岋細VSCode 宸ヤ綔鍖鸿<E98D96>缃?

鍦ㄩ」鐩<EFBFBD>牴鐩<EFBFBD>綍鍒涘缓 `.vscode/settings.json`锛?

```json
{
  "files.encoding": "utf8",
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "editor.formatOnSave": true
}
```

### 鏂规<E98F82>涓夛細鍥㈤槦瑙勮寖

#### 寮哄埗瑙勫垯锛?

1. **绂佹<E7BB82>浣跨敤 PowerShell 鎵归噺淇<E599BA>敼浠ｇ爜鏂囦欢**
   - 鏀圭敤 Node.js 鑴氭湰
   - 浣跨敤 IDE 鐨勯噸鏋勫姛鑳?

2. **鎵€鏈変唬鐮佹枃浠跺繀椤伙細**
   - UTF-8 without BOM
   - LF 琛屽熬绗?
   - 鏂囦欢鏈<E6ACA2>熬鏈夌┖琛?

3. **鎵归噺鎿嶄綔鍓嶅繀椤伙細**
   - Git 鎻愪氦褰撳墠鐘舵€?
   - 鍦ㄧ嫭绔嬪垎鏀<E59E8E>搷浣?
   - 閫愭<E996AB>楠岃瘉锛岃€岄潪涓€娆℃€у叏閮ㄤ慨鏀?

## 馃洜锔?瀹夊叏鐨勬壒閲忎慨鏀规柟妗?

### 浣跨敤 Node.js 鑴氭湰锛堟帹鑽愶級

```javascript
const fs = require('fs');
const path = require('path');

function safeReplace(filePath, searchValue, replaceValue) {
  try {
    // 浣跨敤 UTF-8 璇诲彇
    let content = fs.readFileSync(filePath, 'utf8');
    
    // 纭<><E7BAAD>闇€瑕佷慨鏀?
    if (!content.includes(searchValue)) {
      return false;
    }
    
    // 鎵ц<E98EB5>鏇挎崲
    const newContent = content.replace(
      new RegExp(searchValue, 'g'), 
      replaceValue
    );
    
    // 鍐欏洖锛堜繚鎸佸師鏈夎<E98F88>灏剧<E7818F>锛?
    fs.writeFileSync(filePath, newContent, 'utf8');
    
    console.log(`鉁?淇<>敼鎴愬姛: ${path.basename(filePath)}`);
    return true;
  } catch (error) {
    console.error(`鉂?淇<>敼澶辫触: ${filePath}`, error.message);
    return false;
  }
}
```

### 浣跨敤 TypeScript 缂栬緫鍣?API锛堟渶瀹夊叏锛?

```typescript
// 浣跨敤 ts-morph 搴撹繘琛屽畨鍏ㄧ殑浠ｇ爜閲嶆瀯
import { Project } from 'ts-morph';

const project = new Project({
  tsConfigFilePath: "tsconfig.json",
});

// 閬嶅巻鎵€鏈夋簮鏂囦欢
project.getSourceFiles().forEach(sourceFile => {
  // 浣跨敤 AST 绾у埆鐨勯噸鏋勶紝涓嶄細鐮村潖缂栫爜
  sourceFile.getImportDeclarations().forEach(importDecl => {
    const moduleSpecifier = importDecl.getModuleSpecifierValue();
    if (moduleSpecifier.startsWith('../config/')) {
      importDecl.setModuleSpecifier(
        moduleSpecifier.replace('../config/', '@config/')
      );
    }
  });
  
  sourceFile.saveSync();
});
```

## 馃毃 鍙戠幇涔辩爜鍚庣殑澶勭悊娴佺▼

### 1. 绔嬪嵆鍋滄<E98D8B>鎿嶄綔
```bash
git status  # 鏌ョ湅褰卞搷鑼冨洿
```

### 2. 鎭㈠<E98EAD>澶囦唤
```bash
git restore .  # 鎴栦粠鎵嬪姩澶囦唤鎭㈠<E98EAD>
```

### 3. 浣跨敤瀹夊叏鏂规<E98F82>閲嶆柊鎵ц<E98EB5>

### 4. 楠岃瘉
```bash
# 缂栬瘧妫€鏌?
npm run build

# 鍚<>姩娴嬭瘯
npm run dev
```

## 馃摑 妫€鏌ユ竻鍗?

鍦ㄦ彁浜や唬鐮佸墠锛岀‘淇濓細

- [ ] 鎵€鏈?`.ts` 鏂囦欢缂栫爜涓?UTF-8
- [ ] 娌℃湁 BOM 鏍囪<E98F8D>
- [ ] 浣跨敤 LF 琛屽熬绗?
- [ ] 娌℃湁涔辩爜瀛楃<E7809B>锛堬拷锛?
- [ ] 瀛楃<E7809B>涓查兘姝ｇ‘闂<E28098>悎
- [ ] 娉ㄩ噴娌℃湁鍜屼唬鐮佽<E990AE>鍚堝苟
- [ ] 缂栬瘧閫氳繃锛坄npm run build`锛?
- [ ] 鏈嶅姟鍣ㄥ彲浠ュ惎鍔<E6838E>紙`npm run dev`锛?

## 馃敡 瀹炵敤宸ュ叿鍛戒护

### 妫€娴嬫枃浠剁紪鐮?
```bash
file -bi <filename>  # Linux/Mac
```

### 杞<>崲缂栫爜
```bash
iconv -f GBK -t UTF-8 file.txt > file_utf8.txt
```

### 妫€鏌?BOM
```bash
# Linux/Mac
head -c 3 file.txt | od -A n -t x1
# 濡傛灉杈撳嚭 ef bb bf锛屽垯鏈?BOM
```

### 绉婚櫎 BOM
```bash
# Linux/Mac
sed -i '1s/^\xEF\xBB\xBF//' file.txt
```

## 馃挕 缁忛獙鏁欒<E98F81>

1. **鏋舵瀯浼樺厛锛屽伐鍏峰叾娆?*
   - 姝ｇ‘鐨勬灦鏋勮<E98F8B>璁″彲浠ュ噺灏戞壒閲忎慨鏀圭殑闇€姹?
   
2. **灏忔<E7818F>蹇<EFBFBD>窇锛岄<E9949B>绻侀獙璇?*
   - 姣忎慨鏀逛竴涓<E7ABB4>枃浠跺氨娴嬭瘯涓€娆?
   - 涓嶈<E6B693>涓€娆℃€т慨鏀规墍鏈夋枃浠?

3. **鑷<>姩鍖栨祴璇曟槸鏈€鍚庨槻绾?*
   - 缂栬瘧妫€鏌?
   - Linter 妫€鏌?
   - 鍗曞厓娴嬭瘯

4. **澶囦唤鏄<E594A4>畨鍏ㄧ殑淇濋殰**
   - Git 鎻愪氦
   - 鎵嬪姩澶囦唤鍏抽敭鐩<E695AD>綍
   - 浜戠<E6B59C>鍚屾<E98D9A>

## 馃摎 鍙傝€冭祫鏂?

- [EditorConfig 瀹樻柟鏂囨。](https://editorconfig.org/)
- [Git Attributes 鏂囨。](https://git-scm.com/docs/gitattributes)
- [UTF-8 缂栫爜鏍囧噯](https://www.unicode.org/versions/Unicode15.0.0/)
- [Node.js fs 妯″潡鏂囨。](https://nodejs.org/api/fs.html)

---

**鏂囨。鐗堟湰锛?* 1.0  
**鍒涘缓鏃ユ湡锛?* 2025-11-14  
**鏈€鍚庢洿鏂帮細** 2025-11-14  
**缁存姢浜哄憳锛?* AI Assistant